rest-api-contract

A change is breaking based on direction: in requests, tightening what the service accepts breaks callers, while in responses, removing or narrowing breaks them. Adding a required request field, renaming a field, changing a type, or removing an endpoint are all breaking changes.

Code-first generates the document from controllers via springdoc and suits a single team owning both sides. Contract-first hand-writes the document and generates interfaces, fitting multiple services, external consumers, or parallel teams. A project uses exactly one direction per deployable service.

Yes, in practice. Generated clients commonly fail to deserialize unknown enum values, so treat new response enum values as breaking unless every consumer tolerates unknowns. Document that consumers must accept unknown values to design enums for extension.

Commit the generated document and add a drift-gate integration test that regenerates it via MockMvc and compares parsed trees against the committed copy, failing the build on unexplained differences. Contract-first projects instead validate the implementation against the committed document.

This guidance does not apply to GraphQL, gRPC, event-driven contracts, or gateway configuration. It covers only public REST APIs on Java 21+ Spring Boot, including their OpenAPI documents, versioning, and deprecation.

Mark the operation deprecated with a successor and retirement date in its description, send Deprecation and Sunset headers per RFC 9745 and RFC 8594, and announce directly to known consumers. Never remove before the sunset date and confirm disuse from access logs first.