Request and Response Contracts

A client and a server are usually written by different people, often at the same time, and they meet only in the requests and responses between them. Every field name, type and format they disagree on is a bug that appears only when the two are joined. The contract is the written agreement that lets them be built apart and still fit.

The topic starts with what a contract specifies and how representations and their headers say which format is on the wire. Then it fixes the conventions that recur in every endpoint: names, dates, money and identifiers, the difference between a missing field and a null, and the shape of a list response. OpenAPI shows how a contract is written so tools can check it, and a comparison weighs writing the contract first against generating it from code. A gotcha shows what happens when a database row becomes the contract by accident.

The paths each contract describes come from the previous topic, and the shape of an error response is the next topic's subject.

By the end you can list what a contract specifies, apply the field conventions, tell absent from null from empty, read an OpenAPI operation, choose contract-first or code-first, and shape a list response that can grow.