spring-boot-controller

Spring Boot REST Controller Contract

These rules apply to every REST controller, including when the success body is not JSON. A non-JSON success body is allowed only through an approved Instruction override of the response clause. Server-rendered page controllers (*PageController) and WebSocket endpoints (*SocketController) follow the architecture and Thymeleaf / WebSocket contracts; this file covers REST only.

Architecture, exception handling, i18n, Lombok, and profile/Swagger YAML stay in their own instruction files. Do not restate those contracts here.

Naming

• Name every REST endpoint class <Feature>RestController (architecture contract). The RestController suffix is what loads this file via globs; do not omit it.
• Annotate with @RestController. Do not use @Controller for JSON/API endpoints.
• Never name a REST endpoint class <Feature>Controller, <Feature>PageController, or <Feature>SocketController.
• Never name a server-rendered MVC class <Feature>RestController.

URL design

• Map REST collections at /api/v1/{plural-resource}.
• Do not put a trailing slash on class or method mappings.
• Identify a stored resource with /{id} on GET, PUT, and DELETE.
• Annotate numeric ids with @Positive.
• Keep the version in the path (v1). Do not add a second versioning scheme.

HTTP verbs and payloads

• Use GET, POST, PUT, and DELETE.
• Use PATCH only when the product requires a partial update.
• Send create and update payloads as JSON @RequestBody records, not as query parameters.
• Keep @Valid on the request body (exception and architecture contracts).
• Use one FeatureRequest when create and update share the same fields. Split into CreateFeatureRequest and UpdateFeatureRequest only when the bodies actually differ.

Responses

• Return ResponseEntity<T> from every REST method. Do not return a naked body or a @ResponseStatus void method.
• GET and PUT success: 200 OK with the resource body.
• POST that creates a resource: 201 Created with the body and a Location header for the new resource, built from UriComponentsBuilder.
• DELETE success: 204 No Content with an empty body.
• POST that only accepts work for later processing: 202 Accepted.
• POST that performs an action without creating a resource: 200 OK with the result body.
• Domain misses are thrown as AppException from the service (exception contract). Do not return Optional or an empty 404 from a real-app controller.