Writing Contract-First API Design Documents in English

Contract-first API design is the practice of defining the API contract — typically as an OpenAPI or AsyncAPI specification — before writing any implementation code. The contract becomes the source of truth that both producers and consumers agree upon. Writing this contract clearly, and the surrounding design document that justifies it, is a critical communication skill for backend and platform engineers.

Key Vocabulary

Contract In the API context, a contract is a formal, machine-readable definition of what an API promises to provide: its endpoints, request and response schemas, error codes, and authentication requirements. A contract is binding — both sides of the integration rely on it. Example: “We will finalise the contract by Thursday so both teams can begin implementation in parallel.”

Schema A schema is a structured definition of a data format, describing the fields, their types, and any constraints such as required fields or maximum lengths. In contract-first design, schemas are defined upfront and referenced throughout the specification. Example: “The request schema requires an orderId field of type string and a quantity field of type integer.”

Breaking change A breaking change is a modification to an API contract that is incompatible with existing consumers. Examples include removing a required field, changing a field’s type, or renaming an endpoint. Breaking changes require versioning or a deprecation period. Example: “Renaming the user_id field to userId is a breaking change — we need to version the endpoint.”

Deprecation Deprecation is the process of signalling that an API element is outdated and will be removed in the future, giving consumers time to migrate to a newer version. Example: “The v1 endpoint is deprecated and will be removed in six months. Please migrate to v2.”

Consumer-driven contract A consumer-driven contract is a contract defined by the consuming service, specifying exactly what it needs from the provider. This approach, popularised by tools like Pact, ensures the provider only builds what consumers actually require. Example: “Our consumer-driven contract tests caught the fact that the billing service still depends on a field we planned to remove.”

Common Scenarios Where This Language Is Used

In an API design review: Before development begins, teams review proposed contracts. You will need to articulate your design choices and respond to feedback. “We chose to use a cursor-based pagination scheme rather than offset-based because it scales better with large datasets.”

When communicating a breaking change: If your team needs to introduce a breaking change, you must communicate this proactively to all consumer teams. An email or Slack message should include: what is changing, why, when it takes effect, and what consumers need to do.

In documentation for external developers: If your API is public, your design document becomes developer documentation. The writing must be especially clear, because readers have no context about your internal architecture.

Structure of a Contract-First Design Document

A well-written API design document typically includes the following sections:

Overview: What problem does this API solve, and who are the intended consumers? Keep this concise — two or three sentences.

Design decisions: Explain the choices you made and why. Use a decision log format if multiple alternatives were considered: “We considered X but chose Y because Z.”

Endpoint summary: A human-readable table listing each endpoint, its method, path, and purpose.

Schema definitions: Descriptions of the key data structures, written in plain English alongside the formal schema notation.

Error handling: How the API communicates errors, including the HTTP status codes used and the structure of error response bodies.

Versioning strategy: How changes will be managed over time.

Useful Phrases for API Design Documents

• “This API follows REST conventions and uses JSON for all request and response bodies.”
• “Authentication is handled via Bearer tokens in the Authorization header.”
• “All timestamps are expressed in ISO 8601 format in UTC.”
• “The endpoint returns a paginated list of resources. Use the next_cursor field to retrieve subsequent pages.”
• “This field is required for create operations but optional for update operations.”
• “Clients should treat unrecognised fields in the response as optional and ignore them.”
• “The v1 endpoint is deprecated. Support will be removed on 1 January 2027.”
• “This change is non-breaking — we are adding an optional field to the response.”
• “We recommend polling at no more than one request per second to avoid rate limiting.”
• “The API follows semantic versioning. The major version is incremented on breaking changes.”

Writing Clear Endpoint Descriptions

Each endpoint description should answer three questions: what does it do, what does it need, and what does it return? Keep descriptions concise and use the active voice.

Weak: “This endpoint is used for the purpose of retrieving information about a user.” Strong: “Returns the profile information for the specified user.”

Describe the parameters precisely. Avoid “a string identifier” and instead write “the user’s UUID, as returned by the authentication endpoint.”

Practice Suggestion

Take an existing REST API you work with — or use the GitHub API as a public example. Write a two-page design document for one of its endpoints, as if you were proposing the endpoint for the first time. Include all the sections described above. Invite a colleague to review it and ask whether they could implement the endpoint based solely on your document. Their questions will reveal gaps in your writing.