giuseppe-trisciuoglio/spring-boot-rest-api-standards

¿Qué hace spring-boot-rest-api-standards?

Proporciona estándares de diseño y mejores prácticas para APIs REST en proyectos Spring Boot. Útil al crear o revisar endpoints REST, DTOs, manejo de errores, paginación, encabezados de seguridad, HATEOAS y patrones arquitectónicos.

Convenciones generales

• Nombrado de endpoints: usar sustantivos en plural (/usuarios, /productos), evitar verbos.
• Códigos de estado HTTP: usar códigos estándar (200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error).
• Versionado: prefijar la URL con /v1/, /v2/, etc., o usar headers de aceptación (Accept: application/vnd.ejemplo.v1+json).
• Métodos HTTP: GET para leer, POST para crear, PUT para reemplazar, PATCH para actualizaciones parciales, DELETE para eliminar.

Estructura de respuestas

• Éxito: devolver el recurso directamente o un objeto { "data": {...} }.
• Error: usar un formato estándar como { "error": "mensaje", "detalles": [...] }.
• Paginación: usar Spring Data's Page<T> y devolver metadatos como { "content": [], "page": 0, "size": 20, "totalElements": 100, "totalPages": 5 }.

Manejo de errores

• Implementar un @ControllerAdvice global con ResponseEntityExceptionHandler.
• Devolver errores estructurados con código de error, mensaje legible y detalles técnicos.

DTOs

• Usar record en Java 17+ para DTOs inmutables.
• Separar DTOs de solicitud y respuesta.
• Anotar con Jakarta Validation (@NotBlank, @Size, @Email, etc.) para validación.

Seguridad

• Incluir encabezados de seguridad: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Strict-Transport-Security: max-age=31536000.
• Usar Spring Security para autenticación/autorización (JWT, OAuth2).

HATEOAS

• Agregar enlaces (self, siguiente, anterior) a las respuestas usando EntityModel y Link.
• Ejemplo: { "_links": { "self": { "href": "/usuarios/1" } } }.

Arquitectura

• Seguir principios de diseño orientado al dominio (DDD) o arquitectura hexagonal.
• Separar capas: controladores, servicios, repositorios.
• No exponer entidades de base de datos directamente; usar DTOs.

Documentación

• Usar SpringDoc OpenAPI para generar documentación interactiva.
• Anotar endpoints con @Operation y @ApiResponse.
• Mantener la documentación actualizada con el código.

Buenas prácticas adicionales

• Usar logs estructurados con SLF4J.
• Escribir pruebas unitarias e integrales con JUnit 5 y Mockito.
• Validar entradas siempre, evitar exponer información interna.
• Usar @ExceptionHandler para excepciones específicas de negocio.