API contract

The written promise an API makes about its operations, inputs, outputs and errors, which callers rely on while the code behind it changes.

In more detail

A change that breaks the contract breaks callers even when the code looks correct, so status codes, headers, limits and error shapes are all part of it. It is usually written down in a machine-readable form, such as an OpenAPI document, so tools and tests can check it.

Examples

In the APIs course: In this course the contract is the openapi.yaml file: the service reads it at start-up, the contract suite reads it to decide what to check, and the lessons quote it.
In this course: A contract lists the required fields and what they mean, not every detail a provider happens to emit today. Mocks with invented return values can silently disagree with it; fakes, contract tests and integration tests check it.

Related terms

Taught in

References