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
- OpenAPI — A standard, language-neutral format for describing an HTTP API: its paths, operations, parameters, request and response schemas, errors and security.
- contract testing — Testing that an API’s real behaviour matches its written contract, and that its callers only rely on what the contract promises.
- breaking change — A change that makes existing users of a program or interface stop working until they change something too.
- source of truth — The one authoritative place a fact is recorded, from which every copy is derived instead of being maintained separately.
- DTO — A plain object whose only job is to carry data across a boundary, such as the body of an API request or response.
- Problem Details — A standard JSON shape for HTTP error responses, defined in RFC 9457, with members such as type, title, status, detail and instance.
- contract drift — When the data a server actually sends slowly stops matching what its clients expect, usually without anyone noticing until something breaks.
- design-first — Writing and reviewing an API’s contract, such as an OpenAPI document, before writing the code that implements it.
- single source of truth — The one agreed place where a piece of information is maintained, so every copy is generated from it rather than edited by hand.
- wire format — The exact shape data takes when it travels between programs, such as the field names and types of a JSON body.
- API — A defined way for one program to ask another program to do something, such as a list of web requests a service accepts.
- shared database — One database used directly by several services.
- idempotency key — A unique value a client sends with a non-idempotent request, such as a create, so the server can recognise a retry and return the original result instead of acting twice.
- consumer and provider — The two sides of a contract test: the consumer calls an API and states what it needs, the provider serves it and verifies it keeps the promise.
- over-mocking — Replacing so many collaborators with mocks that tests only check the script the test writer invented, not real behaviour.
Taught in
- What An API Is, And The Alternatives — Modern API Architecture: REST, GraphQL & gRPC
- Versioning APIs — Modern API Architecture: REST, GraphQL & gRPC
- OpenAPI And Design-First — Modern API Architecture: REST, GraphQL & gRPC
- Contract Testing — Modern API Architecture: REST, GraphQL & gRPC
- Building Routes with Controllers — Modern .NET Core, C# & Enterprise Microservices
- Comparing Controllers and Minimal APIs — Modern .NET Core, C# & Enterprise Microservices
- Manual Object Mapping — Modern .NET Core, C# & Enterprise Microservices
- OpenAPI Generation in .NET 9 — Modern .NET Core, C# & Enterprise Microservices
- Monorepo Architecture: Workspaces & Turborepo — Production Full-Stack Engineering
- API Contract Architecture: OpenAPI 3.1 & Schema Truth — Production Full-Stack Engineering
- Type-Safe Client Generation: Orval & Automated SDKs — Production Full-Stack Engineering
- Resilient Error Handling: Problem Details & Envelopes — Production Full-Stack Engineering
- Primitive And Reference Types — Modern Java: Virtual Threads & High-Throughput Services
- Serialization And JSON — Modern Java: Virtual Threads & High-Throughput Services
- Controllers And Routing — Modern Java: Virtual Threads & High-Throughput Services
- Implementing An OpenAPI Contract — Modern Java: Virtual Threads & High-Throughput Services
- The Storage Decision: Relational Versus Document — Scalable System Design & Distributed Architecture
- The Storage Decision: Key Value, Search And Blob — Scalable System Design & Distributed Architecture
- Consistency, And The Truth About CAP — Scalable System Design & Distributed Architecture
- Queues, Events And Asynchronous Work — Scalable System Design & Distributed Architecture
- Timeouts, And Avoiding Cascaded Failure — Scalable System Design & Distributed Architecture
- Retries, Backoff And Jitter — Scalable System Design & Distributed Architecture
- Circuit Breakers — Scalable System Design & Distributed Architecture
- Monolith Versus Services: The Honest Trade Offs — Scalable System Design & Distributed Architecture
- Observability As A Design Input — Scalable System Design & Distributed Architecture
- Worked Design Two: A Global Chat System — Scalable System Design & Distributed Architecture
- Worked Design Two: Scaling Chat Fan Out — Scalable System Design & Distributed Architecture
- Worked Design Three: A Metrics Ingestion Pipeline — Scalable System Design & Distributed Architecture
- Why Over-Mocking Breeds False Positives — Automated Testing, TDD & Quality Engineering
- Integration Testing With Containers — Automated Testing, TDD & Quality Engineering
- Contract Testing Between Services — Automated Testing, TDD & Quality Engineering