API Contracts, Documentation and Evolution

Introduction

A RESTful API is not merely a collection of HTTP endpoints. It is a public agreement between producers and consumers about resources, representations, requests, responses, errors, security, and change. This agreement is an API contract. A well-designed contract allows frontend applications, mobile clients, partner systems, testers, and independent development teams to work in parallel.

Contract quality becomes especially important as an API evolves. A change that appears small to a server developer—such as renaming a response property or tightening validation—may break deployed clients. Consequently, API development requires more than implementation skill. It requires specification, documentation, compatibility analysis, governance, and disciplined communication.

This chapter examines API-first design using OpenAPI and JSON Schema, documentation and SDK generation, compatibility and versioning, deprecation, change control, and consumer communication.

Learning Objectives

By the end of this chapter, you should be able to:

1. Explain the purpose and structure of an API contract.
2. Design an API-first contract using OpenAPI and JSON Schema.
3. Distinguish documentation from an executable contract.
4. Evaluate breaking and non-breaking API changes.
5. Select and apply versioning and deprecation strategies.
6. Establish a change-control and consumer-communication process.
7. Assess generated documentation and SDKs for correctness and usability.

1. API Contracts as Shared Technical Agreements

An API contract specifies observable behavior. It normally identifies:

• available resources and operations;
• HTTP methods and URLs;
• path, query, header, and cookie parameters;
• request and response representations;
• status codes and error formats;
• authentication and authorization requirements;
• validation rules and constraints;
• pagination, filtering, sorting, and concurrency behavior;
• rate limits and operational expectations; and
• lifecycle information such as stability, deprecation, and sunset dates.

A contract has several audiences. Backend developers use it to implement handlers. Frontend developers use it to construct requests and types. Quality engineers use it to generate tests. Technical writers use it to produce reference documentation. Product and governance teams use it to evaluate the impact of change.

Contract-first and code-first approaches

In a code-first approach, developers implement controllers and models first, then generate a specification from the implementation. This can be efficient for a small internal service, but the resulting document may reflect accidental implementation details or omit important behavior.

In a contract-first or API-first approach, the team designs and reviews the contract before implementation. The contract becomes a shared design artifact. Mock servers, validation tests, documentation, and SDKs can be produced before the service is complete.

Neither approach guarantees quality. A code-first workflow can produce an accurate contract if supported by rigorous tests and review; an API-first workflow can produce an elegant but unimplemented specification. The important principle is that the published contract must be explicit, reviewed, testable, and kept consistent with deployed behavior.

2. OpenAPI and JSON Schema

OpenAPI

OpenAPI describes HTTP APIs in a machine-readable format, commonly YAML or JSON. A modern OpenAPI document contains:

• openapi: the specification version;
• info: title, description, and document version;
• servers: deployment URLs or environments;
• paths: operations and their parameters, requests, responses, and security;
• components: reusable schemas, responses, parameters, and security schemes; and
• tags, externalDocs, and related organizational metadata.

A minimal fragment is:

openapi: 3.0.3
info:
  title: Library API
  version: 1.0.0
paths:
  /books/{bookId}:
    get:
      operationId: getBook
      parameters:
        - name: bookId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Book not found
components:
  schemas:
    Book:
      type: object
      required: [id, title]
      properties:
        id:
          type: string
        title:
          type: string

The path template declares bookId as a path parameter. Because it appears in the URL template, it must be required. The response schema states the expected shape, but the specification should also describe semantics such as whether title may be empty, whether unknown properties are ignored, and which error representation is returned.

JSON Schema

JSON Schema defines constraints on JSON instances. Typical keywords include:

For example:

$schema: https://json-schema.org/draft/2020-12/schema
type: object
additionalProperties: false
required: [email, displayName]
properties:
  email:
    type: string
    format: email
  displayName:
    type: string
    minLength: 1
    maxLength: 80

The required keyword concerns property presence, not whether a value is non-null. If email is required and nullable, a schema must explicitly permit null, for example with a type union in the applicable JSON Schema dialect. Validation semantics should therefore be tested rather than inferred from field names.

OpenAPI schemas and JSON Schema dialects

OpenAPI versions have not always supported every JSON Schema keyword identically. OpenAPI 3.0 used a schema vocabulary influenced by JSON Schema but did not fully implement a particular JSON Schema draft. OpenAPI 3.1 aligns more closely with JSON Schema 2020-12. Teams must identify the OpenAPI version, schema dialect, validator, and code-generation toolchain. A keyword accepted by one validator may be ignored or interpreted differently by another.

A robust contract pipeline therefore includes linting, schema validation, example validation, and compatibility testing with the actual tools used in production.

3. Designing an API-First Contract

Start with domain behavior

Design should begin with domain concepts and use cases rather than database tables. A library API might expose Book, Member, and Loan, but it should not automatically expose every database column. The contract should express stable business concepts and operations.

A useful design sequence is:

1. Identify actors and use cases.
2. Define resources and their relationships.
3. Select resource representations.
4. Define operations and expected outcomes.
5. Specify validation and error behavior.
6. Add security and operational requirements.
7. Review examples with representative consumers.
8. Validate and test the contract.

Resource and operation design

Use nouns for resource paths, such as /books and /books/{bookId}. HTTP methods communicate the broad operation: GET retrieves, POST creates or triggers a subordinate operation, PUT replaces a representation, PATCH partially modifies it, and DELETE removes or deactivates it. These meanings are conventions whose precise behavior must be documented.

Idempotency is a property of repeating a request. A request is idempotent when repeating it has the same intended server effect as making it once, although responses may differ. PUT and DELETE are conventionally idempotent; POST is not inherently idempotent. If a payment or order endpoint must safely retry, the API may define an idempotency key and document its storage period, scope, and conflict behavior.

Consistent errors

A useful error response includes a stable machine-readable code, human-readable detail, and correlation information. For example:

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Request validation failed",
  "status": 422,
  "code": "INVALID_EMAIL",
  "detail": "The email address is not valid",
  "instance": "/requests/7f2..."
}

Clients should branch on stable codes or types rather than parsing prose. Error documentation must state which errors are retryable, which require user action, and whether partial success is possible.

Examples as executable communication

Examples often communicate more effectively than abstract schemas. Every important operation should have valid request and response examples, including boundary cases and representative errors. Examples must themselves be validated against the schema. An example that contradicts the schema is a contract defect, not merely a documentation typo.

4. Documentation and SDK Generation

Reference documentation should answer at least five questions:

1. What does this operation do?
2. What must the caller send?
3. What can the caller receive?
4. How should failures be handled?
5. Can the operation be safely retried?

A complete operation page should show its purpose, authentication, URL, parameters, headers, request body, response examples, status codes, error semantics, rate limits, and code samples. Tutorials should explain workflows, while reference pages should precisely describe individual operations. These are different documentation genres and should not be substituted for one another.

Generated documentation

Tools can generate HTML reference pages, interactive consoles, mock servers, and test cases from OpenAPI. Generation improves consistency and reduces manual duplication, but it does not create domain explanations automatically. A generated page may correctly list a field while failing to explain its business meaning, units, lifecycle, or privacy sensitivity.

Documentation should be published from a reviewed specification, not from an arbitrary developer branch. Build pipelines should fail when the document is syntactically invalid, contains unresolved references, violates style rules, or has examples that fail validation.

SDK generation

An SDK maps HTTP concepts into a programming language. It may generate models, authentication support, serialization, retries, pagination helpers, and typed methods. SDK quality depends on operation identifiers, naming conventions, nullability rules, error models, and language-specific conventions.

Generated SDKs require review. Common problems include:

• a nullable server field represented as non-nullable;
• a server enum gaining a value that causes client deserialization failure;
• inappropriate automatic retries for non-idempotent operations;
• loss of response headers needed for pagination or rate limits; and
• generated names that conflict with language keywords.

The SDK is a consumer-facing product. Teams should version it, test it against a live or contract-tested service, publish release notes, and provide escape hatches for advanced HTTP behavior.

5. Compatibility and Change Analysis

A change is compatible only relative to a stated consumer population, protocol, schema dialect, and policy. The following classifications are useful.

The phrase “adding an optional field is always safe” is too strong. A client that rejects unknown properties, a generated model with strict deserialization, or a signed canonical representation may break. Compatibility analysis must consider real client behavior.

Structural and semantic compatibility

Structural compatibility concerns shapes, types, requiredness, and enumerations. Semantic compatibility concerns meaning, ordering, units, authorization, side effects, and timing. Changing a timestamp from creation time to last-modified time may preserve the schema while breaking consumers’ assumptions.

A practical compatibility review asks:

• Can existing valid requests still be accepted?
• Can existing clients parse all responses they may receive?
• Are status codes, error codes, and headers preserved?
• Are authorization and data-visibility rules unchanged?
• Has performance or rate-limit behavior changed materially?
• Do examples, SDKs, and tests still reflect reality?

6. Versioning Strategies

URI versioning

Examples include /v1/books and /v2/books. URI versioning is visible, easy to route, and easy to cache, but can encourage duplicated resources and make version identity part of every link.

Header or media-type versioning

A client may send a version header or an Accept value such as a vendor media type. This keeps URLs stable but makes requests less visible in browsers, logs, and simple documentation. Caches and gateways must vary correctly on the relevant header.

Evolution without frequent versions

Many teams maintain one major API version and make only compatible changes, reserving a new major version for unavoidable breaks. This reduces fragmentation but requires strong discipline, tolerant readers, additive design, and deprecation practices.

Version numbers alone do not solve compatibility. A poorly governed /v2 can break clients just as easily as /v1. Version policy should define what constitutes a breaking change, how long versions are supported, how security fixes are delivered, and who approves exceptions.

7. Deprecation and Sunset

Deprecation communicates that an operation or field remains available but should not be used for new development. A responsible deprecation record includes:

• the deprecated item and reason;
• replacement capability and migration instructions;
• deprecation date;
• planned end-of-support or sunset date;
• telemetry and affected consumers;
• support and escalation channels; and
• security implications.

The HTTP Deprecation response field may communicate deprecation, but its exact syntax and client support depend on the adopted standard and infrastructure. A Sunset response field can communicate a planned retirement date where supported by the organization’s policy. Headers supplement, rather than replace, documentation and direct communication.

Deprecation should be evidence-based. Usage logs, SDK download data, support records, and identified business owners help determine whether retirement is safe. A consumer that has not made a request recently may still have scheduled jobs, disaster-recovery paths, or infrequent annual use.

8. Change Control and Consumer Communication

A mature change process connects design, implementation, testing, release, and communication.

Proposed workflow

1. Change proposal: Describe the motivation, affected operations, alternatives, and expected users.
2. Contract update: Modify the OpenAPI and schema artifacts with examples.
3. Automated checks: Run linting, schema validation, reference resolution, contract tests, and compatibility analysis.
4. Human review: Include domain experts, security staff, support teams, and representative consumers.
5. Implementation: Build the server and update generated artifacts.
6. Pre-release testing: Test old and new clients, negative cases, authorization, and operational limits.
7. Communication: Publish release notes, migration guidance, dates, and support contacts.
8. Controlled release: Use feature flags, canary deployment, or parallel operation where appropriate.
9. Observation: Monitor errors, latency, adoption, and unexpected client behavior.
10. Retirement: Remove the old behavior only after policy conditions and approvals are satisfied.

A change log should distinguish added, changed, deprecated, removed, fixed, and security-relevant items. Migration guides should include before-and-after requests, response differences, code examples, test steps, and rollback considerations.

Retry and backoff as a documented operational contract

Retry behavior is part of an API’s operational contract. An API should identify retryable status codes or conditions, whether a Retry-After value takes precedence, and which methods are safe to retry. Clients should use bounded exponential backoff with jitter rather than synchronized immediate retries.

Let:

• b be the base delay in seconds;
• k be the zero-based retry number;
• C be the maximum permitted delay in seconds; and
• U_k be a random variable uniformly distributed on [0, j], where j ≥ 0 is a jitter allowance in seconds.

A complete-delay cap is:

Here D_k is the actual delay, in seconds. Because the min operation is applied after adding jitter, D_k ≤ C always holds. For example, with b = 1 second, k = 3, C = 10 seconds, and a sampled U_k = 0.6 seconds, the uncapped delay is 1 × 2³ + 0.6 = 8.6 seconds, so the actual delay is 8.6 seconds. If the sample were 3 seconds, the uncapped value would be 11 seconds and the actual delay would be capped at 10 seconds.

This is one possible policy, not a universal law. Another organization may use a full-jitter policy that samples uniformly between zero and a capped exponential bound. Whichever policy is chosen, units, random range, cap location, maximum retries, idempotency requirements, and server instructions must be documented.

9. Security, Privacy, and Governance

Contracts can expose sensitive information even when they contain no production data. Examples must use synthetic identities, tokens, addresses, and payment details. Schemas should avoid returning unnecessary personal data and should identify field-level authorization requirements where relevant.

Security documentation should specify authentication schemes, token audiences, scopes, credential rotation, TLS requirements, and error behavior that avoids leaking resource existence. OpenAPI security declarations are useful but do not replace authorization tests. A documented scope is not evidence that the implementation enforces it.

Governance should establish ownership of the contract, review authorities, retention of old specifications, incident procedures, and audit trails for material changes. Regulatory requirements may affect data minimization, consent, access, deletion, residency, and retention. API evolution must account for these obligations rather than treating compatibility as the only constraint.

10. Illustrative Case: University Library API Migration

Background

A university library operates a v1 API used by a web portal, a mobile application, and two partner institutions. The loan endpoint returns a dueDate string and a numeric memberId.

Problem

The library wants globally unique identifiers, time-zone-aware timestamps, and clearer overdue information. A proposal suggests changing memberId to a UUID, replacing dueDate with dueAt, and returning a new overdue Boolean. The mobile application contains an older SDK that rejects unknown response properties.

Analysis

Changing the type and meaning of memberId is structurally and semantically breaking. Replacing dueDate removes a property and changes temporal precision. Adding overdue is logically additive but is unsafe for the strict mobile deserializer. The team also discovers that partner systems compare the old date as a local calendar date, while the new service stores instants in UTC.

Approach

The team takes the following steps:

1. Publishes an API-impact proposal and identifies all consumers through logs and partner records.
2. Adds a new representation under /v2/loans, preserving the v1 representation during migration.
3. Documents dueAt as an RFC 3339 date-time with explicit time-zone semantics.
4. Provides a migration mapping from numeric identifiers to UUIDs.
5. Releases updated SDKs and a compatibility adapter for the mobile application.
6. Marks the v1 operation deprecated, publishes a sunset target, and supplies test fixtures.
7. Monitors v1 traffic and contacts consumers that continue using it.
8. Delays retirement until scheduled partner jobs have migrated and contract tests pass.

Outcome

The migration avoids a silent semantic change. Consumers receive a stable path to the new representation, and the library can measure adoption rather than guessing. The principal cost is temporary support for two representations, but that cost is lower than an unplanned outage across partner institutions.

Learning points

• A field’s meaning can be more important than its JSON type.
• Consumer discovery is necessary before announcing retirement.
• Additive changes can still break strict clients.
• Dates and times require explicit precision and time-zone rules.
• A migration plan should include tools, examples, telemetry, and ownership.

11. Contemporary Practice and Limitations

Contract testing is increasingly integrated into continuous delivery. Consumer-driven contract tests verify that a provider continues to satisfy actual consumer expectations. Schema-diff tools classify likely breaking changes, but automated classification is not infallible: semantic changes, authorization changes, and performance regressions may escape structural analysis.

AI-assisted tools can suggest schemas, examples, documentation, and migration text. They should not be treated as authoritative. Generated artifacts require validation against specifications, privacy review, security review, and human confirmation of business meaning. An AI system may confidently infer an incorrect field type or expose sensitive example data.

The main limitation of any contract is that it cannot express every operational reality. Queue delays, partial outages, undocumented rate limits, data freshness, and organizational support practices may affect consumers even when the schema is correct. Contracts therefore work best alongside observability, service-level objectives, incident communication, and tested implementation.

Best-Practice Checklist

• Design around stable domain behavior rather than database structure.
• Maintain one reviewed source of truth for the published contract.
• Validate schemas, examples, references, and generated artifacts in CI.
• Document semantics, not only field names and data types.
• Treat error codes, headers, authorization, and retry behavior as contract elements.
• Analyze real consumer behavior before declaring a change safe.
• Use explicit deprecation dates, replacements, and migration guidance.
• Version SDKs and test them against representative service behavior.
• Use bounded, unit-defined retry policies and preserve idempotency.
• Communicate material changes through release notes, direct notices, and support channels.

Chapter Summary

An API contract is a shared, machine-readable and human-interpretable agreement about an API’s observable behavior. OpenAPI describes HTTP operations, while JSON Schema expresses data constraints; their exact capabilities depend on specification versions and validator dialects. API-first design enables parallel work, generated documentation, mock services, contract tests, and SDK production, but generated artifacts still require review.

Compatibility includes structural and semantic behavior. Additive changes may be unsafe for strict clients, and unchanged data shapes may conceal changes in meaning, authorization, timing, or performance. Versioning should be supported by explicit policy rather than treated as a substitute for governance. Deprecation requires replacement guidance, dates, consumer discovery, telemetry, and communication. Change control should connect proposal, automated validation, human review, implementation, controlled release, observation, and retirement. Finally, contracts must address security, privacy, retry behavior, and operational realities as well as resource schemas.

Key Terms

API contract: A formal agreement describing an API’s observable behavior.

API-first: Designing and reviewing the contract before implementing the service.

OpenAPI: A machine-readable specification format for HTTP APIs.

JSON Schema: A vocabulary for validating and describing JSON instances.

Schema dialect: The defined vocabulary and interpretation rules used by a schema validator.

Representation: The data format used to communicate a resource state.

Idempotency: The property that repeating an operation has the same intended server effect as performing it once.

Contract test: A test that verifies agreement between an API provider and its consumers.

Structural compatibility: Compatibility of fields, types, requiredness, and allowed values.

Semantic compatibility: Preservation of meaning, authorization, timing, and operational behavior.

Breaking change: A change that can invalidate an existing consumer’s valid behavior.

Deprecation: Formal notice that a capability should no longer be used, although it remains available.

Sunset: Planned termination of support for a capability.

SDK: A language-specific software development kit for accessing an API.

Tolerant reader: A client designed to ignore response fields it does not recognize.

Retry-after: Server guidance indicating when a client may retry.

Jitter: A randomized delay component used to reduce synchronized retries.

Change control: The governed process for proposing, reviewing, releasing, and retiring changes.

Review Questions

Short Answer Questions

1. What are the principal responsibilities of OpenAPI and JSON Schema in an API-first workflow?
2. Why can adding an optional response property still break some clients?
3. Distinguish structural compatibility from semantic compatibility.
4. What information should a deprecation notice provide?
5. Why must generated SDKs be reviewed rather than accepted without testing?

Long Answer Questions

1. Compare contract-first and code-first API development, including the advantages and risks of each approach.
2. Explain how a team should design and validate a consistent error contract.
3. Compare URI, header, and media-type versioning strategies and identify contexts in which each may be appropriate.
4. Describe a complete change-control workflow for a breaking API change.
5. Explain why dates, time zones, and field meaning create migration risks even when JSON syntax remains valid.

Analytical / Application Questions

1. An API adds a new enum value to a response and changes a 404 response to 204 for one existing lookup. Analyze the compatibility risks and propose a release strategy.
2. A client retries POST /payments after a timeout. Design a documented idempotency and retry policy that prevents accidental duplicate payments.
3. A partner uses a strict JSON deserializer and has not called a deprecated endpoint for six months. Develop an evidence-based retirement plan, including discovery, communication, testing, and rollback criteria.

Multiple Choice Questions with Answers

Question 1

Which artifact primarily describes HTTP paths, methods, parameters, responses, and security schemes?

A. JSON Schema

B. OpenAPI

C. A database migration

D. A deployment manifest

Correct Answer: B. OpenAPI

Question 2

A request property is changed from optional to required without providing a default or alternate operation. How should this change normally be classified?

A. Non-breaking because the property type is unchanged

B. A documentation-only change

C. Breaking for existing callers that omit the property

D. A server-internal change

Correct Answer: C. Breaking for existing callers that omit the property

Question 3

Why is the formula D_k = min(C, b × 2^k + U_k) guaranteed not to exceed C?

A. Because U_k is always zero

B. Because exponential growth stops at retry three

C. Because the cap is applied after the jittered delay is calculated

D. Because b is measured in seconds

Correct Answer: C. Because the cap is applied after the jittered delay is calculated

Question 4

Which statement best describes semantic compatibility?

A. The JSON document contains valid punctuation

B. The documented URL has not changed

C. The response preserves the same business meaning and operational expectations

D. The API uses the same programming language

Correct Answer: C. The response preserves the same business meaning and operational expectations

Question 5

A client rejects unknown response properties. Which proposed change is most likely to break that client despite being additive in the schema?

A. Adding an optional response property

B. Adding a new endpoint that the client never calls

C. Correcting a documentation typo

D. Adding a server-side log field that is never returned

Correct Answer: A. Adding an optional response property

Question 6

What is the most appropriate primary reason for validating examples against schemas?

A. To guarantee that the server has no security vulnerabilities

B. To detect contradictions between documented examples and declared constraints

C. To eliminate the need for human documentation review

D. To make every client tolerant of unknown fields

Correct Answer: B. To detect contradictions between documented examples and declared constraints

Question 7

Which operation is conventionally idempotent but may still require authorization and existence semantics to be documented?

A. POST creation of a new random resource

B. DELETE of a resource

C. A non-repeatable payment command

D. A server-generated event subscription

Correct Answer: B. DELETE of a resource

Question 8

Which item is essential to a responsible deprecation record?

A. Only the date on which the original endpoint was created

B. A replacement capability and migration instructions

C. The source code of every consumer

D. A promise that no monitoring is needed

Correct Answer: B. A replacement capability and migration instructions

Question 9

A service uses b = 1 second, k = 3, C = 10 seconds, and samples U_k = 3 seconds in the corrected complete-delay formula. What delay is used?

A. 8 seconds

B. 8.3 seconds

C. 10 seconds

D. 11 seconds

Correct Answer: C. 10 seconds

Question 10

Which statement about generated SDKs is most accurate?

A. Generation guarantees correct nullability and retry behavior

B. Generated SDKs should be reviewed and tested against representative service behavior

C. SDKs remove the need for versioning policy

D. SDKs can safely retry every HTTP method automatically

Correct Answer: B. Generated SDKs should be reviewed and tested against representative service behavior