Spring REST API Design

Use plural lowercase nouns with kebab-case for multi-word resources and prefix paths with a version like /api/v1/. Map HTTP methods to operations: GET for reads, POST for creation, PUT/PATCH for updates, and DELETE for removal, never putting verbs in URLs.

Separate request and response DTOs using Java Records, placing Bean Validation annotations like @NotBlank and @Email on request DTOs. Never expose JPA entities directly from controllers; map between entities and DTOs with MapStruct or a dedicated mapper component.

Return 200 for successful GET/PUT/PATCH, 201 with a Location header for POST creation, and 204 for DELETE. Use 400 for validation errors, 404 for missing resources, 409 for conflicts like duplicate emails, and never return 200 for errors.

MapStruct is preferred because it generates type-safe mapping code at compile time via a @Mapper interface with componentModel spring. A manual @Component mapper works as an alternative, but mapping logic should never live inside controllers or services.

Accept page, size, and sort query parameters, build a Pageable with PageRequest.of, and return a PageResponse record wrapping the Spring Data Page. The wrapper exposes content, page, size, totalElements, totalPages, and first/last flags.

Controllers should only handle HTTP concerns such as request binding, validation via @Valid, and building ResponseEntity responses. Business logic belongs in the service layer, keeping controllers thin, testable, and decoupled from domain rules.