API Docs 101: Demystifying REST

You don't need to write production code. You need the vocabulary, an API client, and one successful request.

Aug 07, 2026

icon — Photo by Rubaitul Azad on Unsplash

The barrier to writing good API documentation is vocabulary, not programming knowledge. Once you understand what a REST API is, what the component parts are, and what makes a reference page good or bad, you can write and evaluate API documentation without writing production code. You’ll be reading developer-facing material and making test requests, but that’s learnable in days, not years.

That said: you can’t write good API documentation without using the API. Understanding the vocabulary is necessary but not sufficient. You have to make actual requests and see what happens. You need to make bad calls and see what errors you get back and then learn how to fix them.

What an API Is

An API (Application Programming Interface) is a defined way for software systems to communicate. When a developer’s code needs to retrieve data from your product, or send data to it, or trigger an action in it, the API defines how that communication works: what requests are valid, what they look like, and what responses they produce.

You use APIs constantly without seeing them. When a weather app shows tomorrow’s forecast, it’s calling a weather service’s API. When you sign into a site with your Google account, that’s an API call. When a store’s checkout charges your card, it’s calling a payment provider’s API. In each case, one piece of software asks another for data or an action, and gets back structured data rather than a web page. And the calling program uses this data to display, store, or act as it needs. The API is the contract that makes those exchanges predictable: send a request shaped like this, get a response shaped like that.

A REST API (Representational State Transfer) is a specific architectural style that’s become the dominant approach for web-based APIs. REST APIs on the web are built on HTTP, the same protocol your browser uses when it loads a web page. REST itself doesn’t require HTTP (Fielding’s constraints are protocol-independent), but in practice every REST API you’ll document speaks it. This means a REST API request works the same way as a web browser requesting a page, just in a more structured form.

What Makes an API RESTful

REST isn’t a standard you can validate against. It’s a set of six constraints, described by Roy Fielding in 2000. Four ideas shape how you document a REST API. Three of them come out of Fielding’s constraints. The fourth is a convention that HTTP-based APIs settled on, and knowing which is which will save you an argument later.

Resources, addressed by URLs. In REST, everything is a noun: a user, an order, an invoice. Each one has a URL that identifies it. /users/123 is the resource. You don’t put the action in the URL; the action comes from the HTTP method. This is why a well-designed API has a small, predictable set of paths and a handful of methods, rather than endpoints like /getUserById and /deleteUser.

Stateless requests. Each request carries everything the server needs to handle it. The server remembers nothing between calls, and there’s no session holding your place. For documentation, this has a direct consequence: every request example must show its own authentication, because there’s no prior login for the request to lean on.

Standard HTTP methods as the verbs. GET, POST, PUT, PATCH, DELETE (the same five from the anatomy section below) do all the work. This is the one that isn’t Fielding’s. He never specifies a protocol or a set of methods; he only requires that the interface be uniform. But every HTTP-based REST API you’ll document has settled on these five, so a developer who knows what they mean already knows the shape of every REST API they’ll meet.

Representations, usually JSON. When you GET a resource, the server sends back a representation of that resource’s current state, a snapshot, almost always as JavaScript Object Notation (JSON). The resource lives on the server; what crosses over the internet is a description of it.

There’s a fifth idea inside Fielding’s uniform interface that you’ll rarely see honored: hypermedia as the engine of application state. A response is supposed to carry links to the actions available next, so a client starts from a single URL and finds the rest of the API in what the server hands back, rather than holding a hardcoded list of paths. Almost no REST API you document works this way. Most expose a fixed set of endpoints that clients hardcode, and hardcoding is what the constraint was meant to prevent. This is the basis of the argument that most “REST” APIs aren’t REST. It won’t change your job, but it explains the fight if you walk into one.

If you want the full set (all six constraints, and the four sub-constraints inside the uniform interface), go to Chapter 5 of Fielding’s dissertation or the summary at restfulapi.net. Both are in Further Reading. The constraints not covered above shape how systems get built more than how they get documented, which is why they rarely surface on a reference page.

REST won for web APIs because it reuses HTTP instead of inventing a new protocol on top of it. That makes it readable, cacheable, and usable by any tool that already speaks HTTP, including a browser and a plain curl command. You’ll meet a few other styles, and knowing they exist tells you why a given API is documented the way it is.

SOAP is the older, XML-based, contract-heavy approach; you’ll find it in enterprise and legacy systems, rarely in new products.
GraphQL exposes a single endpoint and lets the client ask for exactly the fields it wants. Documenting it means documenting a schema and its types, not a list of endpoints.
gRPC is a fast, binary, service-to-service protocol documented from .proto definitions, mostly used between internal services rather than on public APIs.

REST dominates public web APIs, so it’s where a technical writer starts. When an API doesn’t look RESTful, it usually means you’ve met one of these instead.

The Anatomy of a REST Request

Every REST request has five components that documentation needs to cover:

Endpoint. The URL that identifies what you’re acting on. https://api.example.com/v1/users/123 is an endpoint. The path structure (/users/123) tells you you’re working with a user resource, specifically user 123.
HTTP Method. What you’re doing to the resource. GET retrieves it. POST creates a new one. PUT replaces it entirely. PATCH updates specific fields. DELETE removes it.
Query parameters. Appended to the endpoint after a ?, these filter, paginate, or sort the result: GET /v1/users?status=active&limit=50. They need the same treatment as body fields: name, type, required or optional, default value, and what values are valid.
Headers. Metadata about the request. The most important for documentation purposes is the Authorization header, which carries authentication credentials. API documentation should show what headers are required and what format they expect.
Request body. For POST, PUT, and PATCH requests, operations that send data, the body contains the data. It’s almost always JSON. Documentation needs to show the structure: what fields are accepted, which are required versus optional, what type each field expects, and what the valid values are.

Understanding Responses

The response to a REST request has two parts that matter for documentation: the status code and the response body.

HTTP status codes are three-digit numbers that indicate the result of the request. The ones documentation deals with most:

Documentation that only describes the success case (200) is incomplete. Users encounter errors. A reference page should document every status code the endpoint can return and what the user should do when they get it.

The response body for successful requests usually contains the data the user asked for, in JSON format. Documentation should show an example response and explain every field.

The Tools You’ll Actually Use

Back to the point from the top: you can’t document an API you haven’t used. So before you write, you need a way to send a request and read what comes back. There’s a tool for that at every level of comfort, and you don’t need to pick the fanciest one.

Start with curl at the command line. Many references show their example requests as curl commands, so being able to read and run one is table stakes.

curl -H "Authorization: Bearer TOKEN" https://api.example.com/v1/users/123

That’s an endpoint and a header. The method is implicit: curl sends GET unless you tell it otherwise with -X. Knowing that is the difference between reading an example correctly and guessing at it.

HTTPie is easier for many to use: http GET api.example.com/v1/users/123 with colorized JSON and saner defaults, which makes it easier to read while you’re still learning what a response looks like.

Then there are the graphical API clients, and this is where most writers spend their time:

Postman is the one everyone names. It gives you a form-based way to build requests, save them into collections, chain them, and share them across a team. You build a request once and rerun it every time you revise the doc. It’s the most feature-heavy of the bunch (mock servers, monitors, test scripts). The catch, as of March 2026: the free plan is single-user, and shared workspaces now require a paid Team plan at $19 per user per month, billed annually (postman.com/pricing). For an individual writer just making requests, free is still fine; for a team, price it out.
Insomnia is the leaner alternative, a cleaner interface for the same core loop of build, send, inspect. It supports local, Git, or cloud storage per project, though most features now sit behind a Kong account.
Bruno is the newer, file-first option. It stores each collection as plain-text files (its .bru format) right in your repo, so your API requests get versioned in Git alongside the docs they document. For docs-as-code teams, that’s a natural fit. The core is MIT-licensed and free, though the free tier caps you at two workspaces and five OpenAPI syncs a month. Bruno sunset its one-time Golden Edition license at the end of 2024 and moved to annual subscriptions: Pro at $6 per user per month, Ultimate at $11.
Hoppscotch is the browser-based, open-source choice. Nothing to install, self-hostable, good for a quick request when you don’t want to open a desktop app.

For a technical writer, the practical advice is narrow: learn to read a curl command, and pick one graphical client to make and save requests. Bruno if you’re already living in Git; Postman if your team standardized on it; Hoppscotch if you just want to fire off a request in a browser tab. Pick a client and stop thinking about it. The work is in making the call, reading the real response, and documenting what comes back, errors included.

Ask the development team what they use and recommend.

One boundary: these are clients for using an API by hand. They’re different from the spec-driven tooling that generates reference docs from a machine-readable API definition, like Swagger UI, Redoc, and the OpenAPI ecosystem. Postman and Insomnia can import an OpenAPI file, so the two worlds connect, but the job here is making requests, not generating pages.

What Makes a Good API Reference Page

A complete API reference page covers:

The endpoint URL and method
All parameters (path, query, and body) with type, whether required, and valid values
Required headers
An example request
All possible response codes with descriptions
An example response for the success case
Example responses for common error cases

A good reference page also notes edge cases: what happens at rate limits, what happens with pagination for large result sets, what the maximum request size is.

The test for a complete API reference page: can a developer use it to make a successful request on their first try? If they need to ask questions to fill in gaps, the documentation is incomplete.

Where Reference Pages Consistently Fail

One area that reference documentation consistently underserves: authentication. Most API reference pages list endpoints and parameters but treat authentication as a footnote (”include your API key in the Authorization header”) without explaining how to get the key, what format it takes, how long it lasts, and what happens when it expires. For a developer integrating an API for the first time, authentication is the first obstacle they hit. A reference page that doesn’t give authentication the same depth it gives to endpoint parameters is a reference page that will generate support tickets before a user has made a single successful call.

A second consistent gap is rate limiting. Developers building anything beyond a quick test script need to know the actual numbers: requests per minute, what header carries the remaining quota, what a 429 response looks like, and whether there’s a recommended backoff strategy. Documentation that mentions “rate limits apply” without the specific numbers forces every serious integrator to discover the limit by hitting it in production.

Is Documenting APIs Difficult?

The fear that keeps writers away from API work is that you need to be a programmer. You don’t. The parts that look hard are the small ones: reading a curl command, recognizing the shape of a JSON response, sending a request, and seeing what comes back. None of that is production coding. It’s vocabulary and a little practice, which is the whole premise of this article.

Name what is actually hard, though, because pretending API docs are effortless helps no one.

Access is often the real blocker, and it’s not a technical one. Before you can document an endpoint, you need working credentials, a test account, and usually a non-production environment to make requests against. Request an account and permissions from development.

Authentication is the second, and it’s hard for a specific reason. It’s the most under-documented area in most APIs, which means the source material is thin. You end up reverse-engineering behavior from support threads and engineer conversations instead of reading a spec.

Completeness is the tedious one. Documenting every status code, every error, every edge case is slow, unglamorous work, and tedium is what leaves reference pages half-finished. The success case is easy to write. The error cases are where the support tickets come from.

The last difficulty isn’t a writing problem at all. An API changes in many ways. A field is added, a response shape shifts, or an endpoint is deprecated, and that hand-maintained reference page rots quietly until a developer hits the gap. Keeping the reference in sync is a process problem, and it’s exactly why the next article is about generating docs from a machine-readable spec.

So the fear is misplaced, and the real difficulty sits somewhere else entirely. What separates good API documentation from bad is patience: getting access, making the request, reading the real response, and writing down what actually happens, including the parts that fail.

What You Can Do

Look at your company’s API documentation and pick one endpoint. If you don’t have one, find any public REST API documentation (Stripe, Twilio, GitHub, or any other) to use. Evaluate it against the components described above. Does the page cover all of them? What's missing?

The Way We Write Now

Discussion about this post

Ready for more?