API Documentation: How to write it & Examples

 

API documentation is the interface between your product and every developer who integrates with it. Get it right, and developers onboard themselves, build faster, and advocate for your product. Get it wrong, and you pay in support tickets, lost deals, and failed integrations.

The numbers back this up. Stack Overflow’s 2024 Developer Survey found that API and SDK documentation is the documentation source of choice for 90% of developers, ahead of blog posts, videos, and AI coding assistants. Postman’s State of the API 2024 report (surveying 5,600 developers) found that 39% of developers say inconsistent documentation is the single biggest roadblock to collaboration on APIs, and 44% still dig through source code to understand APIs because the docs are not enough.

So, your developers are going to read the docs. The question is whether what they find when they get there is useful. This guide is for the people who actually build API documentation: platform engineers writing reference, technical writers producing guides, DevRel teams building tutorials, and product managers trying to get the whole thing to hold together. It covers what good looks like, where teams get stuck, and what separates the Stripes and GitHubs of the world from the average internal API portal.

What Makes API Documentation Actually Good

Great API documentation is not a feature list. It is a developer experience that quietly does four things at once, and it does them well enough that nobody notices the docs are doing any work at all.

It shortens the integration path. The first-hour experience of your API is where most abandonment happens. If a developer has to dig through multiple pages to find an auth example or cross-reference two sections to build a basic request, they will either context-switch out or drop the integration entirely.

It shortens onboarding. A well-built Getting Started path takes a new developer from zero to a successful API call in under ten minutes. Companies like Stripe famously optimize for this single metric. If your docs push that threshold past thirty minutes, you have a conversion problem, not a documentation problem.

It drives adoption. Good docs create advocates. A developer who shipped their first integration in an afternoon tells their team about it. A developer who struggled for two days does too, just with different words.

It unblocks internal collaboration. Your own sales engineers, solutions architects, and support team use the same docs your customers do. If the docs are good, the whole company moves faster. If they are not, the tax shows up everywhere, from sales calls to support queue depth.

And for API-first teams, the docs are the product. The API contract, the reference, and the guides together are what your buyer is actually buying. Shipping an API without documentation is like shipping a SaaS product without a UI.

The Three Layers Every API Documentation Needs

There is no single “correct” structure for API documentation. But every production-grade API portal we have seen covers three layers, and the ones that skip a layer always pay for it later.

Reference Documentation (The “What”)

Reference documentation is the full contract. Every endpoint, every method, every parameter, every response schema, every error code. It is the machine-readable source of truth for what your API does, usually generated from an OpenAPI or similar spec.

Reference is where developers go when they already know what they are trying to do and just want to confirm the precise shape of a request. It needs to be complete, accurate, and searchable. Precision matters more than tone. If a parameter accepts a range of 1 to 100, say so in the exact field, not in a paragraph two sections away.

Guides and Tutorials (The “How” and “Why”)

Reference tells developers what the API does. Guides tell them what to do with it. A good guides section walks through common workflows end to end: authenticate, create a resource, handle an error, paginate a list, and build a webhook receiver. Every guide starts from a named job that a developer is trying to finish.

They publish a beautiful reference and call it done. But reference alone leaves developers with a box of parts and no instructions. Guides are where adoption actually happens.

Examples and Code Samples (The “Show Me”)

A working cURL snippet, a Python example, a Node.js sample: these compress minutes of reading into seconds of pattern-matching. Every endpoint in your reference should have at least one language example. Every guide should be runnable from top to bottom.

The best API docs go further and offer sandbox environments, interactive try-it consoles, and copy-paste credentials for testing. The point is not to be fancy. It is to collapse the distance between reading about your API and running it.

How To Write API Documentation, Phase By Phase

The 6 phases of writing effective API documentation: Skipping any one of them shows up later as a drag your developers feel, and you do not see.

Phase one: understand the API before you write a word about it

This sounds obvious. It is not, by someone who read the spec but never ran a single request. The result is docs that are technically correct and practically useless.

Before writing, do the integration yourself. Call every endpoint you plan to document. Trip over the same edge cases your developers will trip over. Understand where the auth flow is fiddly, where the pagination is non-obvious, and where the error messages are cryptic. The quality of your docs is capped by the depth of your own understanding. No writing trick can raise that ceiling.

Phase two: pick the reader and write to them

A payments API for platform engineers needs different docs from a marketing automation API for growth teams. Both are technically “developer documentation,” but the examples, language, and assumptions should look nothing alike.

Before you outline, answer three questions. Who is the primary reader? What do they already know about APIs? What does success look like for them in the first hour? If your API serves multiple personas, you probably need multiple entry points into the docs, not one monolith trying to serve everyone.

Phase three: start with the jobs developers actually try to do

Pull your last ninety days of developer support tickets, forum questions, and sales-engineering escalations. Cluster by root cause. The top ten clusters are your first ten guides. Not the ten endpoints you are proudest of. The ten things developers are actually trying to get done.

This is the difference between docs that read as a tour of your engineering team’s priorities and docs that read as a map of your customer’s priorities. Both are hard work. Only the second one drives adoption.

Phase four: write for scanners, not for readers

Nobody reads API docs end to end. Structure for that behavior.

Descriptive headings. Short paragraphs. Code snippets above the fold. Every section says what job it helps with, in plain English, before it gets into the specifics. “Handling pagination in list endpoints” is a useful heading. “Pagination” is a gamble.

Phase five: include real, working code samples

Every endpoint deserves at least one code sample in the languages your developers actually use. cURL is table stakes. Most teams also cover Python and JavaScript. If your API has official client libraries, the sample should use the library, not the raw HTTP layer. Developers will cut and paste directly from your docs. Make sure what they paste works.

One practical note. Samples go stale when your API changes. Keep them in a repo, test them in CI, and fail the build if a sample stops working. Manual maintenance of code samples is how you end up with docs that tell developers to use deprecated endpoints.

Phase six: review, test with real developers, and ship

Internal review catches typos and factual errors. It does not catch the things that actually matter, like whether a new developer can get from your landing page to their first successful call in under ten minutes.

Before a major docs release, run it past three developers who have never used your API. Sit next to them. Say nothing. Watch where they hesitate. Watch where they have to open a support ticket. Every hesitation is a bug in the docs. Fix the bugs, then ship.

How To Structure Your API Documentation For Maximum Adoption

The structure of your docs portal is itself a piece of documentation. Developers form an opinion about whether your API is easy to work with before they read a single line of prose. A few structural patterns compound over time.

Getting Started goes first, always. The first page a developer lands on should be a ten-minute path from zero to their first successful API call. Authentication, a sample request, a sample response, and a next step. If your navigation buries Getting Started under “Resources” or “Support,” you are leaking developers on page one.

Put authentication upfront. Auth is the first real integration step, and it is where most developers hit their first wall. It deserves its own top-level section, not a subsection inside “Core Concepts.” Show the exact auth flow with real example tokens, and document every error developers are likely to see when they get it wrong.

Group by use case, not by endpoint. Endpoint-first navigation is an org-chart artifact, not a developer mental model. Group by what developers are trying to do. “Accepting payments” is a section. “POST /charges” is a page inside that section.

Publish a changelog. API consumers live in fear of silent breaking changes. A visible, dated changelog signals that you take backward compatibility seriously. Include deprecation notices well in advance of removing anything.

Embed the status page. When a developer suspects your API is down, they should see the answer without leaving the docs. Embedded status and a link to your incident feed signal competence and cut support volume.

API Documentation Best Practices That Actually Move The Needle

Start from a machine-readable specification

OpenAPI, previously known as Swagger, is the closest thing the industry has to a lingua franca for REST APIs. Maintain your spec as the source of truth. Every reference page, every code sample, every SDK should be generated or validated against the spec. This prevents the single most common API documentation failure: the docs and the API drift apart, and the docs are wrong. written guides and tutorials on top. The spec keeps the reference honest. The guides make it useful.

Keep documentation in sync with the API automatically

Any process that relies on a human remembering to update the docs when the API changes will fail. Not sometimes. Always. Bake the docs update into the release process: CI fails if the spec changes and the changelog does not, API versions are tagged in docs the same way they are tagged in code, and deprecated endpoints surface warnings in the reference pages where developers actually look.

Read-only reference is from the last decade. Modern API docs include interactive try-it consoles where developers can run real requests against your API (or a sandbox) without leaving the page. The speed advantage is real. A developer who can make a working call from the docs in five seconds has already started their integration. A developer who has to copy, paste, and configure is still warming up.

Write for multiple audiences without fragmenting the docs

A REST API is often used by several distinct personas: platform engineers building deep integrations, partner developers connecting their product to yours, and internal teams building on top. They all need the same reference, but they do not all need the same onboarding. Use progressive disclosure: one set of high-level guides for partners, deeper architectural notes for platform engineers, and a shared reference that serves both.

Make search work the way developers search

Developer search behavior is specific. They search for exact endpoint names, error strings, parameter names, and SDK method signatures. Your search has to handle all of those, plus natural-language questions from developers who do not yet know the vocabulary of your API. Document360’s Eddy AI search understands semantic context and surfaces related articles, while the search analytics dashboard shows you exactly what developers searched for and did not find. Treat failed searches as a backlog. Each one is a page that your docs are missing.

Track documentation performance like you track product metrics

If your docs do not have analytics, you are flying blind. At minimum, track page views, search queries, helpful-or-not votes, and drop-off points in key tutorials. Document360’s built-in analytics show article views, the exact search terms developers used, helpful and not-helpful votes, and the path each developer took through the documentation. The point is not to produce a dashboard. The point is to ship docs, measure what confuses developers, and rewrite the pages that keep losing them.

💡 Don’t Miss: API Documentation Tools: Key Features, Pros & Cons

Common API Documentation Mistakes We Keep Seeing

We audit a lot of API documentation portals during Document360 migrations. The same handful of mistakes show up in almost every audit. None of them is exotic. All of them are fixable.

Auto-generation is a starting point, not a finishing point. Raw OpenAPI-to-HTML output produces an accurate reference that developers still cannot use, because the spec does not carry the context, warnings, and examples that humans need. Treat auto-generated output as the skeleton. Wrap it in human-written guides, annotated examples, and real context about what each endpoint is actually for.

Ignoring versioning until it is too late

API versioning is inevitable. The moment you have external consumers, breaking changes become political, and you will ship v2 while v1 is still in production. If your docs do not handle version coexistence from day one, you end up with support tickets from customers reading the wrong version of the docs for their integration. Document360’s version control lets you maintain multiple documentation versions simultaneously with easy switching, so developers on v1 and v2 APIs both see accurate documentation without stepping on each other.

Shipping reference only and calling it done

A docs portal with only reference works like a dictionary with no phrasebook. Developers can look up any word, but they cannot form a sentence. Every production API needs reference, guides, and examples. If your team is stretched, write fewer guides that are genuinely useful rather than many guides that exist to tick a box.

Treating documentation as a one-time launch task

Docs rot. APIs evolve, new features ship, edge cases get discovered, and customer questions reveal gaps. Documentation that was accurate at launch is stale within six months if nobody is maintaining it. Assign a named owner. Build a quarterly review cadence. Make docs part of the release checklist, not a line item in a spreadsheet nobody owns.

Treating authentication as a footnote

Auth is where most integrations fail. A weak auth section (no code samples, no error reference, no clarity on token lifecycle or scopes) converts directly into support tickets and lost integrations. Dedicate a full section to it. Show success cases and failure cases. Document every error developers will see when auth goes wrong, along with the fix.

▶️ Check Out How to Create API Documentation with Document360

 

Three API Documentation Examples Worth Studying

The best way to calibrate your own docs is to study the ones developers genuinely love. Three API documentation portals most teams benchmark against and what each does particularly well:

Stripe

Stripe’s docs are the reference that every API team quietly tries to imitate. The single best thing they do is the side-by-side layout: prose explanation on the left, live code sample on the right, with the code sample updating as you navigate. The second-best thing they do is obsessive attention to time-to-first call. Their quick start is genuinely ten minutes, and the authentication story is unusually clear for a system with as many edge cases as payments.

Twilio

Twilio’s strength is the density of working code examples. Nearly every concept comes with runnable snippets in multiple languages, and the guides are organized around outcomes (send a message, receive a call, verify a phone number) rather than endpoints. Their Getting Started flow assumes nothing and works for developers who have never touched telephony before. For a domain that is genuinely complicated, that is a significant achievement.

GitHub

GitHub’s API documentation is a masterclass in managing scale without drowning the reader. They manage a REST API, a GraphQL API, and dozens of webhooks, and the docs scale to match. Notable moves: version switching baked into the top of every page, clear deprecation notices for old endpoints, and an OpenAPI spec developers can download and use to generate their own SDKs. If your API is anywhere near as sprawling as GitHub’s, their docs are the template to copy.