REST API Conventions for Spring Boot 4

API contract review

The agent first inspects existing controllers, DTOs, exception handlers, OpenAPI definitions, security rules, and MockMvc tests. It treats existing response formats and route conventions as compatibility requirements rather than replacing them with a generic envelope.

Endpoint design

• POST /api/v1/orders validates a dedicated request DTO, delegates business rules to the service, returns 201 Created, and includes a Location header.
• GET /api/v1/orders/{id} returns the established order response DTO and maps missing resources to 404.
• GET /api/v1/orders accepts bounded page and size parameters, deterministic sorting, and the project's existing pagination response shape.
• Domain entities remain inside the persistence layer and are never serialized directly.

Error handling

Validation failures, malformed requests, missing resources, conflicts, and unexpected failures are mapped through one controller advice using Spring's ProblemDetail support. Every error uses application/problem+json and includes stable machine-readable fields without exposing stack traces or implementation details. Successful responses keep their normal media type and are not wrapped in Problem Details.

Tests delivered

Focused MockMvc tests cover successful creation, Location headers, validation errors, not-found behavior, conflict mapping, pagination bounds, deterministic ordering, content types, and authorization behavior. Service behavior is mocked only at the controller boundary.

Next steps

Run the controller and contract tests, compare the generated OpenAPI document with the prior version, and verify that API consumers tolerate only the intentional additions.