liveBook · Manning

Contract

As explained in Grokking Software Architecture

An API contract specifies the operations, data, and behavioral expectations governing communication between an API and its clients.

An API contract is a public promise between a client and a server: which requests are available, what data they exchange, and how the server responds. Like a restaurant menu, it gives customers useful choices without inviting them into the kitchen. The server can change its internals while clients continue to rely on the same promise. section 6.3 section 6.3.1

A clear contract spells out the parts of an exchange:

  • Endpoint and method: where to send a request and what operation it performs, such as GET /api/v1/orders/123. section 6.3.2
  • Headers: metadata such as authorization and content type that sets the rules for the request and response. section 6.3.2
  • Request and response bodies: the expected data structures and fields, which need not be identical in both directions. section 6.3.2
  • Status codes: how the server signals the result of the exchange. section 6.3.2 section 6.3.1

Behavior matters too. An idempotent operation can be repeated without repeatedly changing system state. For example, PUT can leave an order in the same updated state after a retry, while repeating a purchase POST may create duplicate charges. Choose methods and retry protections with that difference in mind. section 6.4.1 section 10.4.1

Refactoring a profile contract

Suppose a profile API uses POST /api/changeUserAddress to update an address and returns a raw address string from GET /api/data/user_info. Before writing the implementation, identify the profile resource, choose HTTP methods for reading and updating it, and design an extensible JSON object instead of a bare string. section 6.10.2

A published contract is harder to change than an internal method: clients may be owned by other teams or run on devices you cannot update. Removing or renaming a response field, changing its type, or adding a required parameter can break those clients. Adding an optional parameter or response field can be compatible when existing clients ignore what they do not use. section 6.3 section 6.3.3

The hidden promise

An API promises a list of users but says nothing about order. If it has returned users alphabetically for years, a client may depend on that order anyway. Switching databases and returning a different order can break the client without violating the written description. Consider observable behavior as well as documentation when planning a versioned change. section 6.3.4

Choose the contract style for the job. REST offers resource-based operations and predictable responses; GraphQL offers flexible querying. For AI agents as well as human developers, descriptive endpoint and field names reduce ambiguity. Version the interface carefully and support existing consumers as they migrate. section 6.12 section 6.5.2 section 6.3.3

How Grokking Software Architecture covers it

How deep it goes
Defines exchange clauses and retry behavior, then examines breaking changes, implicit dependencies, and versioning.
Examples
Uses a restaurant menu, a user-profile redesign exercise, and an unexpectedly reordered user list.
What you can do after
Practice designing and reviewing a resource-based API contract for methods, extensible data, and compatibility.
How it connects
Connects API contracts to decoupling, idempotency, REST, GraphQL, and 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 Grokking Software Architecture. The section links point to the parts of the book it draws on.