What This Template Covers
The API contract template covers five core areas that together define a complete, usable API specification. The OpenAPI 3.0 structure section provides the skeleton of a valid OpenAPI specification with the info, servers, paths, components, and security sections filled in according to best practices for SaaS APIs. OpenAPI 3.0 is the current standard for REST API documentation and is supported by a wide range of tooling including automatic client SDK generation, documentation hosting, and mock server creation. The authentication pattern section covers the two most common authentication models for SaaS APIs: API key authentication for machine-to-machine integrations, and JWT bearer token authentication for user-context API calls. Both patterns are documented in a way that is directly usable in the OpenAPI spec and in integration documentation. The error response schema section establishes a consistent error format across all API endpoints. Inconsistent error formats are one of the most common complaints from developers integrating with SaaS APIs. A standardised error response with a machine-readable error code, a human-readable message, and optional details reduces integration friction significantly. The versioning policy section defines how the API will evolve over time without breaking existing integrations. Versioning policy is a decision that should be made before the API is published, not after the first breaking change needs to be made. The rate limiting documentation section covers how rate limits are communicated to API consumers through response headers and how the API behaves when limits are exceeded.
How to Use This Template Step by Step
Step one: complete the info section of the OpenAPI spec. This includes the API title, version, description, terms of service URL, contact information, and licence. For a production SaaS API, every field in the info section should be completed. The description should include a brief overview of what the API does, the base URL, and where to find authentication credentials. Step two: define the servers section. For a SaaS API, you typically have at least two servers: production and a staging or sandbox environment. Document both, clearly labelled. For APIs that support multiple regions, add a server entry for each region with a clear description. Step three: define the security schemes. In the components/securitySchemes section, define your authentication methods. For API key authentication, use the apiKey type with the header name where the key is sent (typically X-API-Key). For JWT bearer authentication, use the http type with bearer scheme. Apply the appropriate security scheme to each path or globally. Step four: define the paths. For each endpoint, document: the HTTP method, the operation ID (a unique, descriptive name used in generated SDKs), a summary (one sentence), a description (detailed behaviour including edge cases), the request body schema if applicable, the path and query parameters, and the response schemas for all expected status codes including error cases. Step five: define the components. Move all reusable schema definitions into the components/schemas section and reference them from paths using $ref. This keeps the specification DRY and makes it easier to maintain. Define separate schemas for request bodies and response bodies even if they are similar. Step six: document the error response schema. Define a standard error response schema in components/schemas and reference it from every error response in every path. The schema should include at minimum: an error code (machine-readable string), a message (human-readable description), a request ID (for support and debugging), and an optional details field for additional context. Step seven: write the versioning policy document. Decide on a versioning strategy: URL versioning (v1 in the path), header versioning (API-Version header), or date-based versioning. Define what constitutes a breaking change and what does not. Establish the deprecation policy: how much notice will API consumers receive before a breaking change, and how will they be notified? Step eight: document rate limits. Add response header documentation for X-RateLimit-Limit (maximum requests per window), X-RateLimit-Remaining (remaining requests in current window), and X-RateLimit-Reset (Unix timestamp when the window resets). Document the 429 Too Many Requests response with the Retry-After header.
Section-by-Section Walkthrough
The paths section is the core of the OpenAPI specification and where most documentation effort goes. For each endpoint, the description field (not the summary) is where the important detail lives: the exact conditions under which each response code is returned, the behaviour for edge cases (what happens if an optional field is omitted, what happens if the resource does not exist, what happens if the requesting user does not have permission), and any side effects of the operation. For SaaS APIs with organisation-based multi-tenancy, every endpoint that returns data should document how tenancy is enforced. The documentation should state explicitly that only data belonging to the authenticated user's organisation is returned or affected, and what happens when a request targets a resource belonging to a different organisation (always a 404, not a 403, to prevent enumeration). The authentication section should include example code in at least two languages showing how to authenticate. Curl examples are universally useful. Adding a Python and JavaScript example increases the utility significantly for developer-facing APIs. These examples belong in the API description, not the OpenAPI spec itself. The error response schema should be designed to support both human debugging and automated error handling. Machine-readable error codes (not HTTP status codes, which are too coarse, but application-level codes like SUBSCRIPTION_REQUIRED or RESOURCE_LIMIT_EXCEEDED) allow API consumers to handle specific error types programmatically. The request ID field is essential for support: when a developer reports a problem, they can provide the request ID and you can trace the exact request through your logs. The versioning policy section should address three specific scenarios: adding a new optional field to a response (non-breaking, no version bump required), removing or renaming a field from a response (breaking, requires version bump and deprecation notice), and changing the behaviour of an existing endpoint without changing the schema (grey area, handle case by case with clear documentation).
Common Mistakes This Template Prevents
The most common API documentation mistake is documenting only the happy path. Real API integrations always encounter error cases: authentication failures, invalid inputs, resource not found, rate limit exceeded, server errors. If these are not documented, the developer integrating with the API has to handle them by trial and error. This template's error response schema and the requirement to document all response codes for every endpoint prevents incomplete documentation. The second mistake is not establishing a versioning policy before the first public API release. Once external developers have integrated with the API, any breaking change requires either breaking their integration or maintaining the old version in parallel. Establishing the versioning policy before publication creates the expectation and the process for managing evolution. The third mistake is inconsistent field naming conventions. An API where some fields use camelCase, some use snake_case, and some use kebab-case is difficult to use and document. Establish a convention (camelCase for JSON responses is most common for JavaScript-consumer APIs) and enforce it across the entire specification. The fourth mistake is not documenting authentication errors separately from authorisation errors. A 401 Unauthorized response means the request was not authenticated (no valid credentials). A 403 Forbidden response means the request was authenticated but the user does not have permission. Confusing these, or returning only one of them, makes it harder for API consumers to diagnose authentication problems.
Customisation Tips for Different Project Types
For internal APIs consumed only by your own frontend application, a lightweight API contract is sufficient. You still benefit from a consistent error format and documented endpoints, but you do not need the full versioning policy and deprecation process that a public API requires. Use the OpenAPI spec as living documentation that is generated from code annotations (tools like tRPC or Zod-based validators can generate OpenAPI specs automatically), which keeps the documentation in sync with the implementation. For third-party developer platform APIs, the documentation needs to go beyond the OpenAPI spec to include a developer portal with getting-started guides, authentication flow documentation, webhook documentation (separate from REST endpoint documentation), and an API changelog. The OpenAPI spec is the machine-readable foundation, but human-readable guides are equally important for adoption. For regulated API integrations in UK financial services, the API contract should address FCA Open Banking standards if applicable, the data fields that constitute regulated financial data, and the audit logging requirements for API calls that trigger regulated actions. The FCA expects firms to maintain records of customer-facing API interactions under SYSC data retention rules. For AI product APIs that return AI-generated content, add documentation of the AI-specific response fields: confidence scores if exposed, the model version used to generate the response, the input token count and output token count for billing transparency, and any content filtering flags. These fields help API consumers make informed decisions about how to present or act on AI-generated content.