What an API contract actually is

An API contract is the promise your service makes to its callers. The URLs, the methods, the required fields, the shape of responses, the status codes you return. Once clients depend on the contract, changing it without coordination is a breaking change, and breaking changes break customers.

Code, spec, and the feedback loop

Code and spec live next to each other. A contract test fails in CI when they drift apart. The feedback loop keeps them honest automatically.

Every API has a contract, whether you write it down or not. The difference between a professional team and an accidental one is that the professional team writes it down and publishes it. That way, the contract lives in one place, reviewers can spot breaking changes, and tools can validate against it.

Two flavors of change to remember. Additive changes are safe: new optional fields on requests, new fields on responses, new endpoints. Clients that ignore the new stuff keep working. Breaking changes are dangerous: removing a field, changing a field type, renaming an endpoint, tightening a required field. Those need versioning or coordinated deploys.

Quiz: Quiz

Loading practice…