API Specification (OpenAPI)

Purpose

API specifications provide a contract between API producers and consumers, enabling parallel development, automated testing, code generation, and clear documentation. They are the single source of truth for how an API behaves.

When to Use

Create during alpha when designing APIs. The specification should be written before implementation (design-first approach) and maintained as the API evolves. Publish on the organisation's API catalogue.

How to Build

Start with the API's purpose and scope — what resources does it manage? What operations are supported? Who are the consumers?

Define the resource model: what entities does the API expose? How are they related? Use RESTful conventions for URL structure.

For each endpoint, specify: HTTP method, URL path, path/query parameters, request body schema, response schemas for success and error cases, and authentication requirements.

Define reusable schemas for common data structures. Use JSON Schema for request/response bodies. Include examples for each endpoint.

Specify error responses consistently: use standard HTTP status codes, include error detail schemas, and document rate limiting behaviour.

Tips

Use design-first approach — write the spec before the code, not after.
Follow GDS API design standards for government APIs.
Include realistic examples for every endpoint — they serve as documentation and test data.
Version your API from day one — breaking changes need a new version.
Publish the spec on your API catalogue and keep it in sync with the implementation.
Use tools like Spectral for linting and ensuring consistency.

Common Mistakes

Writing the spec after implementation, leading to inconsistencies.
Not including error response schemas, leaving consumers guessing about failure modes.
Using inconsistent naming conventions across endpoints.
Not versioning the API, making evolution impossible without breaking consumers.
Omitting authentication and authorisation details from the specification.

Government Context

In UK government, APIs should follow the GDS API technical and data standards. Government APIs should be published on the cross-government API catalogue. RESTful JSON APIs are the standard; use of SOAP should be justified. APIs handling personal data must document their lawful basis under UK GDPR. The API specification supports the Technology Code of Practice principle of using open standards.