What is an API design doc — written before the API, not after.
Short answer
An API design document is a written proposal for a new or changed API that describes the endpoints, request/response shapes, authentication, error handling, and versioning strategy — before any code is written. It's reviewed by both producers (the team building the API) and consumers (the teams or users who will call it), allowing feedback to shape the design while changes are still cheap. It's the difference between designing an API and discovering one after the fact.
APIs are hard to change once they're in production. Clients take dependencies on the exact shape of requests and responses, so breaking changes require versioning strategies, deprecation periods, and coordinated migrations. The best time to make design changes is before any client has integrated — which means the API design doc must be written before implementation begins.
What an API design doc is not. API documentation (like a Swagger/OpenAPI spec or a reference guide) describes an API that already exists. An API design doc proposes an API that is being designed — it's a proposal for review, not a reference for consumption. After the API is built and released, the design doc becomes a historical artifact; the OpenAPI spec or reference docs replace it as the canonical source of truth.
Standard sections.
Overview. What problem does this API solve? Who are the consumers? What will they use it to build? 1–2 paragraphs framing the purpose.
Resources and endpoints. The URL structure, HTTP methods, and a description of each endpoint. Use a consistent naming convention. Show representative requests and responses for each endpoint — real JSON, not pseudocode.
Request and response shapes. Field-level documentation for each object: name, type, required/optional, constraints, example values. Flag fields that may be nullable or polymorphic — these are the sources of most integration bugs.
Authentication and authorization. How does the consumer authenticate? Bearer tokens, API keys, OAuth 2.0? What scopes or permissions are required for each endpoint?
Error handling. What HTTP status codes are used, and for what conditions? What does the error response body look like? Is the error format consistent across all endpoints? Error design is the most neglected part of API design docs.
Versioning strategy. Is this API versioned in the URL (/v1/), in a header, or not at all? What is the compatibility commitment — semver, additive-only changes within a major version, or full backward compatibility forever?
Rate limiting. Are there rate limits? What headers communicate remaining quota and reset time?
Pagination. How are large collections paginated — cursor-based, offset/limit, or page-based? What is the maximum page size?
Open questions. Design decisions that need input from consumers or platform stakeholders before the API is finalized.
Review process. Share the design doc with consumer teams (the developers who will call the API) before implementation. Collect feedback async for 1 week. A 30-minute review meeting resolves open questions. This step prevents the "we built it wrong" discovery 6 months into integration.
When the API is designed at a whiteboard — endpoint sketches, data model, flow diagrams — snap the board with BoardSnap. The AI reads the resource structure and flow and produces a first-draft API design doc outline ready for engineering review.
Frequently asked
What's the difference between an API design doc and API documentation?
An API design doc is prospective — it proposes how an API will be designed, before implementation, and is used to gather feedback and make design decisions. API documentation (OpenAPI/Swagger specs, reference guides, tutorials) is retrospective — it describes an API that already exists and is used by developers integrating with it. Design docs become obsolete once the API ships; documentation must be maintained as the API evolves.
Should an API design doc use OpenAPI format?
It can use OpenAPI for the endpoint and schema definitions — most teams do, because it can be turned directly into documentation and mock servers. But the OpenAPI spec alone isn't sufficient as a design doc; you also need the rationale sections (why these resources, why this design choice, alternatives considered) that OpenAPI doesn't capture. A good API design doc has both the spec-level detail and the rationale prose.
Who reviews an API design doc?
The team building the API (producer team) and the teams or developers who will call it (consumer teams). Consumer feedback is the most important — they're the ones who will suffer if the design is wrong. Ideally, at least one end-to-end scenario is traced through the API design during review to verify that consumers can accomplish their primary tasks without workarounds.
See it work in ten seconds.
BoardSnap is free on the App Store. Snap a board — get a summary and action plan.