By the Octri team · Updated
What is API documentation? Parts and examples
An API is a contract written for computers. Its documentation is the part that makes the contract usable by people who did not design it. It explains what an endpoint does, which request it accepts, what comes back, and how the pieces fit together into a task.
The best test of API documentation is whether an unfamiliar developer can use it without asking the author to fill in missing details.
What does API documentation include?
Most APIs need four kinds of information. A getting-started path helps the reader make the first call. Task guides explain how to accomplish something meaningful. The API reference describes the exact request and response contract. Change notices tell developers when that contract evolves and what they need to do about it.
Authentication, errors, SDK examples and search connect these areas. A reference with no quickstart can be precise but hard to enter. A polished tutorial with no reference can get someone started but leave them unable to handle the second use case.
API documentation, defined
For an HTTP API, documentation names the resources, methods, paths, authentication, parameters, request bodies, responses and errors. It also explains the concepts behind those facts. If the API returns money in the smallest currency unit, the documentation says so. If two resources have a parent-child relationship, a guide explains what that relationship means in practice.
An OpenAPI specification can encode much of the contract in JSON or YAML. Human-facing documentation uses that information as a foundation and supplies the explanations, examples and workflows that a schema alone cannot teach.
The audience includes developers evaluating the API, developers implementing it, teams debugging failures, internal maintainers and coding assistants retrieving the same material to generate integration code.
The four parts of API documentation
Start with Get started: a short overview, an authentication explanation and a quickstart with one successful request. This should be the most inviting route through an unfamiliar API.
Then build Guides around actual tasks, such as “Create and send an invoice,” instead of just the internal resource model. The API reference is organized differently: it should be complete, consistent and easy to scan while a developer is coding. Finally, Changes includes the changelog, version policy, deprecation notices and migration instructions.
A developer may move between these areas many times in one afternoon. Linking them is as important as having them.
What an API reference entry looks like
I traced a real example for this article without making a live change: I opened GitHub's Create an issue API reference and asked what I would need to create an issue safely.
The page gave me POST /repos/{owner}/{repo}/issues, the required owner and repo path values, and a request body with title as the required field. It also named the fine-grained token permission for creating issues, listed response codes including 201 Created, and explained two easy-to-miss behaviors: the endpoint can return 410 Gone when issues are disabled, and creating content too quickly can trigger secondary rate limiting.
That last part changed how I thought about an “endpoint description.” If I had only copied the path and request body, I could have written a happy-path call. I would not have known what permission to request or why a valid-looking request might fail even when the JSON was correct.
I did not submit an issue; doing that would have required choosing a real repository and authorizing a change. The review was enough to test the documentation's usefulness for someone preparing an integration. It also showed the limits of a reference: to build a complete issue-tracking workflow, I would still need guidance on how the application finds repositories, handles notifications and deals with retries.
Here is the shape of a request, with placeholders for a real token and repository:
curl -X POST \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H 'Accept: application/vnd.github+json' \
-H 'X-GitHub-Api-Version: 2026-03-10' \
https://api.github.com/repos/OWNER/REPO/issues \
-d '{"title":"Export fails with a server error"}'The version shown is an example of an explicitly supported GitHub REST API version; a real integration should select a version according to its compatibility needs. The docs should always make that selection visible.
API documentation vs an API specification
A specification is structured input for tools. For an OpenAPI-defined HTTP API, it expresses paths, operations, schemas and security requirements in machine-readable form. Documentation is the reader-facing experience built around those facts.
The distinction is useful because they fail differently. A complete spec with poor descriptions produces a technically comprehensive but unhelpful reference. A beautifully written guide based on a stale spec can teach a request the server no longer accepts. Keep the contract and the explanation connected, and test both against a running API.
OpenAPI's official learning materials explain how the specification describes HTTP interfaces.
Types of API documentation by audience
Public documentation helps developers decide whether to adopt a platform and learn it independently. Partner docs may include private workflows, restricted endpoints or business-specific onboarding. Internal documentation serves other teams, new employees and on-call engineers who need to understand service behavior quickly.
The underlying needs overlap: a trustworthy reference, discoverable guidance and change history. What differs is the access model, level of explanation and whether a reader can ask the API's authors for help.
AI assistants introduce another consumer of the same material. They benefit from the OpenAPI source and readable text versions of pages, but still require current information and unambiguous descriptions.
Where API documentation lives
Documentation may live as a README in a repository, as Swagger UI served beside the application, or as a hosted site on a domain such as docs.example.com. Those are delivery choices rather than different definitions of documentation.
A small service with one experienced audience may work well with a README and generated reference. A public platform typically benefits from a searchable site with getting-started guides, endpoint references, version policies and an obvious route to support.
Publish clean Markdown where agents may need to read pages programmatically, and protect private material with real access controls rather than relying on obscure URLs.
How API documentation is made
The reference is commonly generated from OpenAPI, while the written guides are composed and reviewed by people who understand the product. A release pipeline can regenerate parameter pages and examples, but someone still needs to decide whether a task guide explains the right sequence of operations.
Try to keep both kinds of content close to the code that changes them. When an endpoint gains a required permission, the source spec, API reference and relevant guide should all communicate the new behavior together.
What makes API documentation good
A good documentation site helps the reader recognize success and diagnose failure. That means complete examples with expected responses, precise authentication and scopes, useful error explanations, clear version labels and links between task guides and the reference.
It also uses consistent names. If the product calls something a “workspace,” the guide should not casually rename it a “project” while the API uses a different identifier. Accurate terminology keeps readers from building the wrong mental model.
During the GitHub reference review, the most helpful details were the ones that anticipated trouble: permission requirements, disabled issues and rate limiting. Those facts turn a basic request description into a usable contract.
A quick check of your API documentation
Choose an operation that matters to new developers and read its docs without relying on what you know about the implementation. Can you find the correct request, required credential, expected response and recovery instructions? Does the page say which version it describes? If the operation is part of a larger workflow, can you reach the relevant guide in one step?
Then test the instructions with someone outside the API team. Every question they ask because the page is silent is a candidate improvement. Do this regularly, especially after changing authentication, pagination or response semantics.
API documentation with Octri
Octri API Studio can generate endpoint references from OpenAPI and combine them with written guides, SDK request examples and an interactive playground. Markdown output and an llms.txt index can also make published material easier for coding assistants to retrieve.
Those are tools for presenting a contract and its explanations. The hard part remains the same as in the GitHub example: give the reader enough context to make a request safely, understand what happens and keep building without having to ask what the documentation forgot to say.