API Reference Documentation: How to Structure Endpoints, Examples, Errors, and SDK Paths
Learn how to structure API reference documentation for endpoints, parameters, examples, errors, pagination, authentication, and SDK paths.
Team Docuwiz
Documentation Experts
Sign Up for Docuwiz
Experience the magic of collaborative documentation with Docs-As-Code Workflow
Quick Answer: What is API reference documentation?
API reference documentation is a structured, authoritative description of how developers interact with an API. It defines the available operations, required inputs, access rules, returned data, and possible errors so developers can implement and troubleshoot API calls.
A complete API reference should cover:
API structure: Organize the reference into APIs, resources, operations, and shared schemas.
Methods and paths: Identify each operation’s HTTP method, endpoint path, purpose, and expected behavior.
Authentication and inputs: Explain access requirements, parameters, request bodies, data types, constraints, defaults, and required fields.
Requests and responses: Provide schemas and realistic examples showing what developers send and receive.
Status codes and errors: Describe successful responses, failure conditions, error details, and corrective actions.
SDK and guide links: Connect operations to relevant SDK methods, recipes, task guides, and troubleshooting pages.
Unlike tutorials and guides, which teach developers how to complete a task, API reference documentation helps them look up exact contract details while implementing or debugging an integration.
Below, we’ll explore how to structure clear, useful API reference documentation and how Docuwiz supports the workflow.
What is API reference documentation?
API reference documentation explains how developers can interact with an API. It shows which endpoints are available, how to access them, what information to send, what the API returns, and what errors may occur.
Developers use the reference while building or debugging an integration. They might open it to check whether a field is required, understand a response, or find out what an error code means.
API reference documentation is different from a tutorial or guide. A guide explains how to complete a task. A reference provides the exact details needed to make an API call. For example, “How do I create an invoice?” belongs in a guide, while “Which fields does POST /invoices accept?” belongs in the reference.
GOV.UK’s API reference guidance recommends covering resources, endpoints and methods, parameters, example requests and responses, and error codes. A complete reference may also include authentication, environments, version information, and links to SDKs or related guides.
Teams can use the underlying OpenAPI file to validate the API description, support testing, and generate SDKs or API client code.
How API reference fits into wider API documentation
An API reference is one part of a complete documentation set. The Diátaxis documentation framework separates technical documentation into four types based on what the reader needs to accomplish:
Content type | Reader’s job | Typical content |
|---|---|---|
API reference | Look up an exact contract detail | Operations, parameters, schemas, responses, errors |
Tutorial | Learn by completing a guided project | Prerequisites, ordered steps, working result |
How-to guide | Complete a specific task | Goal, decisions, steps, troubleshooting |
Explanation or conceptual guide | Understand a system or model | Architecture, terminology, behavior, trade-offs |
Keep reference pages focused on exact API details. If developers need to complete a longer workflow, add a short purpose statement and link to the relevant guide. Keep required authorization scopes, parameters, response fields, and errors on the reference page where developers can find them quickly.
A developer portal is different from these four content types. It is a website or interface through which developers can discover APIs, read documentation, and, when supported, request access or test API calls. Use the portal to connect references, guides, tutorials, explanations, and developer tools through clear navigation and search.
GOV.UK’s broader API documentation guidance recommends documenting rate limits, versions, support, and service status. A practical approach is to maintain this shared information on dedicated pages and link to it from the API overview or relevant endpoint pages.
How should you structure an API reference?
A clear hierarchy helps developers move from the API overview to a resource and then to a specific operation. They should not need to understand your internal architecture to find an endpoint.
A practical API reference hierarchy includes:
API overview: Explain what the API does, who it is for, how to access it, which environments and versions are available, and where to get support.
Resource or capability groups: Organize operations under names developers recognize, such as Customers, Invoices, or Payments.
Operation entries: Give every method and path a consistent entry covering its purpose, access requirements, inputs, responses, errors, and examples.
Shared rules and components: Document common authentication requirements, headers, rate limits, error formats, and reusable schemas once. Include pagination, idempotency, or retry behavior when the API supports them.
Related documentation: Connect operations to relevant SDK methods, task guides, webhooks, migration instructions, and changelog entries.
OpenAPI can support this structure. In OpenAPI 3.1.1, tags can group operations by resource or another logical category, Operation Objects contain operation-level details, and the Components Object holds reusable definitions. The specification provides the underlying structure, but teams still need to choose clear group names, descriptions, and navigation.
Organize the reference around the things developers work with, not the internal systems that power them. For example, group the operations for creating, retrieving, and refunding payments under Payments, even if different backend services handle each action. A developer looking for refunds should not need to understand your internal architecture.
What should an API endpoint reference include?
A useful endpoint reference should quickly answer four questions: What does this operation do? What must the developer send? What will the API return? What can go wrong?
Document every operation in a consistent order. Remember that the HTTP method is part of the operation: GET /payments/{paymentId} and DELETE /payments/{paymentId} use the same path but perform different actions.
Use the following structure to present each operation clearly:
Section | What to include |
|---|---|
Purpose | A short explanation of what the operation does and when to use it |
Method and path | The HTTP method, endpoint path, and relevant base URL or environment |
Access requirements | The authentication method, required scopes or roles, and any account restrictions |
Inputs | Path, query, header, and cookie parameters; request body; accepted content types |
Request example | A minimal valid request and, when useful, a more realistic example |
Successful responses | Status codes, response headers, schema, field descriptions, and example bodies |
Error responses | Status codes, error details, likely causes, and what the developer should do next |
Additional behavior | Pagination, idempotency, rate limits, retries, or deprecation details when they apply |
Related documentation | Relevant SDK methods, guides, webhooks, related operations, and changelog entries |
This structure aligns with GOV.UK’s API reference guidance, which recommends documenting endpoints and methods, parameters, example requests and responses, and error codes.
The OpenAPI 3.1.1 Operation Object supports much of this information through fields such as summary, description, parameters, requestBody, responses, security, servers, and externalDocs. OpenAPI provides the structure, but it does not guarantee that descriptions are clear, examples are realistic, or developers can find the related guidance they need.
Document shared information once. For example, if every operation uses the same authentication method or error format, explain it on a shared page and add a short reminder or link from each operation. Any exception that applies to a specific operation should appear directly in that operation’s reference.
Make endpoint details useful in practice
The endpoint structure provides the right information, but the quality of that information determines whether developers can use it without trial and error. Pay particular attention to four areas:
Parameters: Explain what each parameter controls, where it appears, whether it is required, which values it accepts, and what happens when it is omitted or invalid. For example, “Maximum number of invoices returned per page; accepts 1–100 and defaults to 25” is more useful than “Number of results.”
Examples: Pair important operations with a minimal valid request and a matching response. Identify required scopes, units, API versions, and values generated by the server. Use obvious placeholders for secrets and validate examples against the current schema.
Errors: Document the HTTP status, a stable error code or type, the likely cause, and what the developer should do next. Include retry guidance when relevant. RFC 9457 defines the Problem Details format for HTTP APIs, which can provide machine-readable information beyond the status code.
SDK links: Show developers how an endpoint maps to the corresponding SDK method, including the package, language, and supported version. A consistent OpenAPI operationId can help teams maintain this mapping, although generated method names may differ between SDKs.
Shared authentication rules, error formats, and other common behavior can live on dedicated pages. Keep operation-specific requirements and exceptions directly on the endpoint page.
Keep the reference usable and current
An OpenAPI Description can encode the methods, paths, parameters, schemas, security requirements, servers, and responses used to generate reference pages. Treat that generated output as a starting point. Teams still need to improve descriptions, validate examples, explain errors, and connect endpoints to relevant guides and SDKs.
For a large API, group operations under recognizable public concepts and provide clear search terms, version labels, section links, and connections between related operations. Make active, beta, and deprecated operations easy to distinguish.
Reference quality also needs clear ownership. Engineering should verify contract behavior, technical writers should improve clarity and consistency, and product, DevRel, support, and QA should surface workflow or troubleshooting gaps. Include documentation review whenever a release changes an endpoint, field, scope, error, or SDK method, and assign one person to approve the final public page.
API reference quality checklist
Before publication, confirm the reference against your technical requirements and applicable accessibility criteria such as WCAG 2.2:
☐ Every public operation appears under the correct resource or tag.
☐ Method, path, server, version, and lifecycle state are accurate.
☐ Authentication, authorization scopes, and environment rules are visible.
☐ Every parameter states purpose, type, requirement, constraints, and omission behavior.
☐ Request and response schemas match the implementation.
☐ Examples use safe data and pass validation or test calls.
☐ Common and endpoint-specific errors include corrective action.
☐ Pagination, idempotency, retry, and limit behavior appear where relevant.
☐ SDK links point to compatible methods and versions.
☐ Guides, status, support, changelog, and migration paths are linked.
☐ Search labels, anchors, related endpoints, and version indicators work.
☐ A developer, writer, and release owner reviewed the page.
☐ Keyboard navigation, contrast, mobile layout, tables, and code blocks are usable.
How does Docuwiz support API reference documentation?
Creating endpoint pages is only one part of maintaining an API reference. Teams also need to validate the source, improve the surrounding content, review changes, and publish a reference that developers can navigate and test. Docuwiz brings these activities into one API documentation workspace.
Build references from OpenAPI: Teams can import an OpenAPI description, run OAS validation, and generate structured endpoint pages from the specification. References can be organized by path or tag, allowing developers to browse the API using public-facing resources and operations.
Make endpoints easier to use: Reference pages can display the method and path, server details, parameters, response sections, generated cURL, and response examples. A Try Now action lets developers test an operation when the endpoint and credentials are configured. Copy OAS and Download OAS options keep the underlying specification accessible.
Connect reference and guidance: Docuwiz keeps guides and API references in the same workspace. Its guide editor supports visual editing, Markdown, and preview, while Recipes can combine explanatory pages and endpoint operations into a task-oriented sequence.
Review and publish changes: Comments, revisions, and publish states support feedback around guides and references. Teams can import documentation from GitHub or GitLab and push selected updates back with a commit message. The published portal brings together guides, references, recipes, search, and a branded presentation for readers.
Docuwiz does not replace documentation ownership. Engineers still need to maintain the API contract, while writers, DevRel, product, and QA improve explanations, examples, navigation, and release readiness. It provides those contributors with a shared workflow for converting an OpenAPI description into usable developer documentation.
Conclusion
An API reference is both a contract and a maintained reader experience. Start with a stable hierarchy, then make every endpoint page predictable: purpose, access, inputs, examples, responses, errors, operational behavior, and next paths.
OpenAPI supplies the machine-readable foundation. Human review supplies context, realistic examples, usable navigation, and accurate SDK links. Keep both under ownership, test them together, and the reference becomes a dependable implementation tool instead of an endpoint inventory.
FAQs
What is API reference documentation?
API reference documentation is a structured description of an API’s resources, operations, parameters, schemas, responses, errors, and access requirements. Developers use it to implement calls and confirm exact contract details.
What should an API reference page include?
Include the operation’s purpose, method and path, authentication and scopes, parameters, request body, examples, success responses, errors, and relevant operational behavior. Add links to SDK methods, guides, support, and lifecycle information.
What is the difference between API reference and API documentation?
API documentation is the complete set of content supporting an API. The API reference is one part of it, alongside tutorials, how-to guides, conceptual explanations, changelogs, status information, and support content.
Can OpenAPI generate API reference documentation automatically?
Documentation tools can generate the structural foundation of a reference from a sufficiently complete OpenAPI Description. Teams still need to review summaries, constraints, examples, errors, navigation, version labels, and links for clarity and accuracy.
How should API parameters be documented?
State each parameter’s purpose, location, type, format, required status, accepted values, default behavior, constraints, interactions, and invalid-input response. Explain what the schema alone does not reveal.
How do you document API errors and response examples?
Show safe response bodies that match the current schema. For errors, include the HTTP status, stable code or problem type, meaning, likely cause, corrective action, and retry guidance where applicable.
How should an API reference link to SDK documentation?
Map each operation to the relevant SDK package, class, method, example, and supported version. Record naming or behavior differences and verify the link whenever the API or SDK changes.
Who should review API reference documentation?
Engineering reviews contract accuracy, writers review clarity and structure, DevRel or support contributes recurring integration issues, and QA verifies examples, versions, and links. A named release owner gives the final public page one accountable approver.
Related reads
Written by
Team Docuwiz
Documentation Experts
The Docuwiz team helps developer-focused companies build documentation their users actually love — from API references to onboarding guides and everything in between.
