API reference vs guides: what goes in each

Those are different kinds of questions. They deserve different kinds of documentation.

The distinction between API reference and guides matters because developers move between learning a system and working with it all day. When the docs treat those jobs as interchangeable, a simple lookup becomes a long read, and a tutorial turns into a catalogue of parameters. The result may be technically complete and still unpleasant to use.

What is the difference between an API reference and a guide?

An API reference documents the contract. It lets someone check the exact path, accepted arguments, authentication requirements, and possible responses of a particular operation. You typically arrive there knowing roughly what you want to call.

A guide starts with a goal. It helps you connect operations in the right order and understand the decisions along the way. You might arrive knowing only that you want to launch an instance, accept a payment, or synchronize customers.

There is a little more to it than a two-column split. Diátaxis, Daniele Procida's approach to documentation, identifies four purposes: tutorials for learning, how-to guides for completing a goal, reference for looking things up, and explanation for developing understanding. In everyday API documentation, the first, second, and fourth often get grouped under “Guides.” Their purposes are still worth keeping distinct when you write.

A beginner may need all four in a single afternoon. They work through a quickstart, look up the meaning of a field, read why a webhook can be delivered twice, and return to the code. Good navigation lets them make those transitions without starting over.

What goes in an API reference?

Suppose a developer is about to call POST /v2/droplets. They're not looking for a lesson in infrastructure. They're checking which properties the request requires, how authentication works, and what the service returns while a Droplet is being created.

For that reader, a reference page should have a dependable shape. Put the method and path where they can see them immediately. Describe the operation in a sentence or two. Follow with authentication and scopes, path and query parameters, the request body, success and error responses, and complete request examples. If the API is versioned, make the version being described unmistakable.

The quality of a reference often comes down to the descriptions that sit beside a field. region: string is technically useful; a description that explains which regions are available, what happens when the value is omitted, and whether the region can change later saves somebody from finding those answers experimentally. The same goes for an enum value, a nullable response field, or an idempotency header. Those are contract details, so they belong near the thing they qualify.

A reference should also make failures visible. If an operation can return 401, 403, 409, or 429, document the circumstances and the response shape, not merely the status numbers. Somebody implementing retries needs to know whether a failure is temporary. Somebody debugging permissions needs to know which scope to request.

The screenshot below is an unofficial DigitalOcean API showcase built with Octri. It illustrates the anatomy of an endpoint page: request fields, example client code, a sample response, and a way to try the call. The interesting part is not the layout by itself. It's that a developer can inspect the contract without stepping out of the task they're already doing.

An OpenAPI specification can describe much of this structure, which is why generating reference pages from it makes sense. Generation does not make the prose accurate by itself. A missing field description stays missing when a renderer puts it in a beautiful table. The spec still needs authors and reviewers who understand the API.

What goes in guides?

Consider what happens immediately after that first server-creation call. The API might return an identifier before the server is usable. To complete the task, the developer has to check its state, decide when to proceed, and perhaps create or attach another resource. The endpoint reference gives them the necessary operations. A guide shows how those operations form a sensible workflow.

A useful guide begins with an outcome the reader recognizes: Create a server and connect to it, not An introduction to server resources. It makes the prerequisites clear, uses an example that reaches a visible result, and explains the decisions that won't be obvious to a newcomer. Once the reader can complete the task, it gives them a route to the next one.

There is a telling example of what happens when this material is compressed too aggressively. In a 2009 essay about writing Django's documentation, Django co-creator Jacob Kaplan-Moss looked back at the project's own tutorial. He acknowledged that it glossed over the distinction between a project and an app. That kept the early lesson moving, but, in his words, the shortcut “bites users later on.”

He was describing a framework tutorial rather than a REST API. The tension is the same, though. A first successful result matters, but a beginner can follow every command and still miss the concept that makes the next task possible. Adding an exhaustive reference table to the tutorial wouldn't have fixed that. A focused explanation of the project/app distinction, introduced when the reader was ready for it, would have addressed the gap without slowing the first lesson to a crawl.

Kaplan-Moss also argued that a great reference is of little use if a reader doesn't know what to look up. His example was Python's collections.deque: good material exists for the type, but someone who doesn't know it exists needs an introduction to the available data structures before the reference can help. That is a particularly useful test for API guides: do they teach the names and concepts people need to navigate the reference on their own?

For most APIs, the written side of the docs needs a short quickstart, task-oriented how-to guides, and explanations for concepts that cut across endpoints: authentication, pagination, webhooks, retries, and rate limits. A tutorial teaches the newcomer through one manageable exercise. A how-to guide assumes a little more context and gets a specific job done. An explanation supplies the mental model that makes both easier to use.

The quickstart pictured below, from an unofficial DigitalOcean showcase built with Octri, begins with a goal and prerequisites before moving into numbered steps. That's useful even for experienced developers: it makes the path through unfamiliar software explicit without asking the reader to inspect every endpoint first.

Which should you write first?

Start by making sure the contract is written down. If you have an OpenAPI file, you can render an initial reference from it without inventing hundreds of endpoint pages by hand. Review the result for missing descriptions, absent error responses, and examples that could never run. That provides a reliable base to link to as you write.

Then build the quickest useful journey through the API. Choose something a newcomer can recognize as success, preferably with a result they can verify. A quickstart that makes one request, receives an identifiable response, and explains what to do next will teach you more about your documentation gaps than spending a week polishing the navigation.

There is no need to wait until the entire reference is perfect to publish a quickstart. In fact, writing that first journey often exposes gaps in the specification: a required header that nobody described, a status code that isn't listed, or two operations that have to be called in a particular order. Fix the spec when you find those problems, so the reference improves for every reader.

After that, prioritize authentication and error handling, followed by the handful of tasks that account for most real integrations. If people repeatedly ask how to retry a failed webhook or paginate through results, the missing piece is probably a guide, even when every relevant endpoint is already documented.

Link guides to the reference

Once you have both kinds of pages, the biggest maintenance mistake is to write the contract twice.

A guide that walks through creating a server needs a working request with realistic values. It doesn't need to reproduce every optional property and response field from the creation endpoint. Those belong in the reference, where they can be found and updated together. The guide can explain why it chooses a particular region or instance size, while linking the reader to the operation for the full set of options.

The same relationship should work in reverse. An endpoint that returns an asynchronous job identifier can link to a guide on handling long-running operations. A webhook operation can link to the explanation of signature verification and retries. When somebody lands on a reference page from a search result, they should be able to discover the surrounding workflow without guessing which navigation section might contain it.

There's one practical exception worth making explicit: a guide's example must remain runnable. Don't remove a required header or field from the sample merely because it's documented elsewhere. Duplication of the minimum necessary code is useful; duplication of entire reference tables is what creates drift.

Organize them in navigation

A newcomer should be able to recognize the route into a task, and an experienced user should be able to reach an endpoint quickly. Those needs suggest two visible entry points, usually Guides and API reference, rather than a long sidebar that mixes concepts and operations without a pattern.

Within the reference, organize by the nouns and resources the API exposes: customers, invoices, subscriptions, servers. Within guides, use the reader's goals and level of familiarity: getting started, core concepts, common workflows, advanced integrations. Keep the names consistent across the two. If the reference calls a resource a “Droplet,” changing it to “virtual machine” only in the guides makes search and cross-linking harder than it needs to be.

A well-designed docs site doesn't require everyone to start on its home page. A link from a support reply, an AI coding assistant, or a search engine may land on a deep endpoint page. Give that reader enough orientation to see which API version they're on, what task this operation belongs to, and where the related guide lives.

Common mistakes

The most familiar problem is a perfectly serviceable OpenAPI reference published as the entire documentation site. Every operation is listed, but a newcomer has no idea which one to call first. This is why a standalone Swagger UI reference can work well for an internal service whose consumers already know the domain, yet leave a public API feeling unfinished.

The reverse is also common: a detailed tutorial that contains so many parameter descriptions it takes ten minutes to find the next instruction. That material may be correct today, but it is hard to scan and expensive to maintain after the API changes. Other failures are subtler: a reference with field descriptions that repeat the field names, a guide that hides authentication prerequisites, or code samples that nobody actually runs before publishing.

The Django tutorial problem Kaplan-Moss described is another reminder. Simplifying the first lesson is reasonable. Leaving readers with a misleading mental model is not. When an explanation is too long for the quickstart, write it separately and link to it when its absence would start causing mistakes.

API reference and guides best practices

The most useful improvement is often to test a complete reader journey. Pick a task, hand the documentation to somebody who didn't build the API, and observe where they stop. Do they search for an operation whose name they don't know? Copy a request with an undocumented header? Reach the right response but misunderstand what to do next? Each hesitation tells you which type of page needs work.

Keep the specification responsible for the exact contract. Make the reference predictable, with meaningful descriptions and both success and failure responses. Give each guide one recognizable outcome. Use examples that work from a clean environment and link to the reference for optional behavior. If a workflow requires an explanation, make it discoverable from the guide and from the relevant operation.

Finally, review the two kinds of content together when you ship. Regenerating a reference after a spec change will not repair a human-written guide that still tells people to use the old sequence of calls. A release is complete when the contract and the recommended workflow agree.

API reference vs guides checklist

• Every supported endpoint has a reference page generated from a reviewed API description.
• Required inputs, defaults, allowed values, scopes, response codes, and errors are documented.
• Code examples show a complete request and a representative response.
• The quickstart ends with a result the reader can verify.
• Task guides cover the main things developers are trying to build.
• Authentication, retries, pagination, webhooks, and other shared concepts have explanations where needed.
• Guides link to the operations they use; reference pages link back to the relevant workflows.
• Both are easy to find in navigation, with consistent resource names and version labels.
• Example requests are tested, and guides are reviewed when the API changes.

API reference and guides with Octri

Octri API Studio puts these two kinds of documentation in the same publishing workflow. An OpenAPI spec becomes an endpoint reference with request fields, responses, client examples, and a playground. The pages that explain how to use those endpoints can be written in the visual editor or as MDX, organized beside the reference, and linked to the relevant operations.

That arrangement takes care of the mechanics of publishing a reference and making guides available in one place. It still leaves the most important editorial decision with the people who know the API: which details belong in the contract, which belong in a step-by-step task, and where a reader will first need the explanation. If those choices are clear, both pages become more useful and considerably easier to maintain.