A public API is a contract with its users: they depend not only on its interface, but also on its constraints, assumptions, and expected behavior. Once others rely on it, changing exposed behavior can break their systems and cost time, money, and trust. section 9.4.1 section 9.5
Make the contract understandable to the people who depend on it. Depending on the interface, document method signatures and parameters; input, output, and error formats; limits and pagination; authentication and access rules; versioning and deprecation; performance expectations; and required dependencies or configuration. section 9.4.1
Separate a response from an internal entity
Returning database entities directly from a REST API exposes the internal data model. A schema change can then affect external users, and private information may leak. Use a clear response model instead, exposing only what clients need while keeping implementation details private. section 9.4.1 section 9.5
Keep the public surface small: every exposed detail is another commitment to maintain. Preserve backward compatibility for as long as possible. When a public interface must change, communicate through documentation, deprecation notices, and semantic versioning so users can adapt. section 9.4.1 section 9.5
Store contract documentation alongside the implementation when practical, so it can follow the same review process and be updated with related code changes. Contracts may be declared in code, generated from annotations, or maintained as versioned schema files. Executable specifications and tests can also illustrate and validate expected behavior. section 3.2.1

























































