api-contract-review

Review each endpoint for correct HTTP verb usage, URL versioning, DTO-based request and response bodies, proper status codes, and consistent error formats. A structured checklist covering semantics, design, and compatibility ensures nothing is missed.

Common mistakes include using POST for idempotent updates, returning JPA entities directly, omitting API versioning, returning HTTP 200 with error bodies, and exposing stack traces in error responses. Each of these breaks client expectations or leaks internals.

URL path versioning like /api/v1/users is recommended because it is explicit, easy to route, and simple to test. Header and query-parameter versioning keep URLs clean but are harder to discover and easier to forget.

Breaking changes include removing endpoints or response fields, adding required request fields, changing field types, renaming fields, and changing URL paths. Safe changes include adding optional request fields, new response fields, and new endpoints.

Returning JPA entities exposes internal fields like password hashes and internal IDs, and can trigger lazy-loading N+1 query problems. Mapping entities to response DTOs exposes only intended public fields and decouples the API from the database schema.