liveBook · Manning

Contract

As explained in The Art of Code

A public API is an externally accessible software interface whose operations and behavior are exposed for use by other systems or clients.

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

How The Art of Code covers it

How deep it goes
Explains contract contents, exposure risks, documentation maintenance, and compatibility practices without detailing a specific contract implementation.
Examples
Contrasts exposed database entities with clear REST response models to illustrate coupling and information-leak risks.
What you can do after
Evaluate public interfaces for unnecessary exposure and compatibility risks, and communicate unavoidable changes to users.
How it connects
Connects contracts to encapsulation, backward compatibility, automated testing, and semantic versioning.

Also explained in

Compare how 58 books explain contract →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Art of Code. The section links point to the parts of the book it draws on.