API Reference, Use-Case Guide or Integration Tutorial?

Use a use-case guide to help a reader decide whether the product fits a task, an API reference to describe an operation precisely, and an integration tutorial to guide a bounded implementation. Connect them with purposeful links rather than expecting one page to satisfy all three needs.

The difference is the reader's desired outcome. An evaluator needs suitability and constraints. A developer checking a field needs an exact contract. Someone implementing for the first time needs setup, ordered steps and a way to verify success. Mixing these jobs can leave a long page that answers none of them cleanly.

This article shows three small documents for the same fictional Example Events service. The facts stay consistent while the presentation changes. The examples illustrate documentation design, not the capabilities of an actual commercial API or a proven way to earn AI citations.

Choose the page by the task

Diátaxis distinguishes tutorials, how-to guides, reference and explanation as different documentation needs. A use-case guide in this article is an editorial page for product suitability, drawing on explanation and decision support. It is not a claim that Diátaxis defines a fifth category with that name.

The taxonomy is useful only if it improves navigation and writing. Small products can combine compatible material. A short reference can include a complete example, and a tutorial can link a concise explanation. The boundary matters when one job starts obscuring another.

Keep one contract behind every document

Before writing the examples, establish a shared fact sheet. For the fictional service used here:

• A trusted backend submits one event through POST /v1/events.
• A server credential authorizes access in the real-product concept; the accompanying local teaching fixture uses a known fake token instead.
• The body contains a non-empty name string and a properties object.
• A successful submission returns an event identifier with status: accepted.
• Acceptance does not prove downstream delivery or processing.
• The local fixture stores receipts in memory and loses them when stopped.

The distinction between a product concept and a teaching fixture must remain visible. Do not let a fake local credential become the implied production authentication procedure. Likewise, do not add a delivery guarantee in the use-case guide that the reference never establishes.

Maintain a fact sheet or shared contract source as the docs evolve. A writer can change explanations independently while an API owner verifies that behavior remains consistent across pages.

Example 1: a use-case guide for suitability

The following is an illustrative mini-document, written for a team evaluating event acceptance rather than copying a request immediately.

Accept application events from a backend

Example Events illustrates a service that accepts named application events and returns a receipt. It fits a workflow where the sending application needs to know that an event was accepted before handling later processing separately.

The integration belongs on a trusted backend. A server credential should not be embedded in browser code. If a browser action creates the event, the application needs an appropriate backend path and its own authorization checks before forwarding the event.

The event includes a name and an object of properties. Keep the payload limited to what the task requires. A receipt confirms acceptance only; a product requiring verified downstream completion also needs a documented completion mechanism, which this example does not supply.

Start with the local tutorial to understand the request cycle. Use the endpoint reference when building or checking a request. Evaluate retention, throughput, deployment and delivery behavior against a real product's documented guarantees before making a purchasing decision.

That mini-document gives an evaluator a useful answer without pretending to be a complete API reference. Its limitations are part of the fit assessment, not a footnote after a broad promise.

Example 2: an endpoint reference for exact behavior

The reference should let a reader verify details quickly. It does not need to repeat the entire product argument or provide every setup instruction inline.

Accept an event

Operation: POST /v1/events in the illustrative contract. Media type: application/json. Authorization: bearer credential; use the actual service's documented issuance and permissions. The local exercise substitutes a fake local token and must not be treated as production authentication.

Required fixture header: Idempotency-Key: tutorial-workspace-001. The key must be nonblank and at most 128 characters; a missing or invalid key returns 400. The fixture compares exact request body text and stores keys and receipts only in memory until the server stops.

Example body:

{
  "name": "workspace.created",
  "properties": {
    "workspace_id": "ws_example_001"
  }
}

Success returns 202 with a receipt:

{
  "event_id": "evt_1",
  "status": "accepted"
}

In the teaching fixture, malformed JSON or an invalid event body returns 400; an invalid token returns 401. Its local idempotency behavior is defined by the fixture: identical body text with the same key reuses a receipt, while changed body text with that key returns 409. This is not a universal behavior of all APIs using an idempotency header.

For the complete local behavior, inspect the downloadable server in the integration tutorial. A production reference should additionally document limits, complete error schemas, identity scope and durability rules. The small example does not establish those properties.

OpenAPI's Operation Object provides a machine-readable structure for operation details such as inputs, responses and security. Pin the specification version your tooling supports and keep the prose consistent with it. Schema validity does not prove an implementation behaves correctly.

Example 3: a tutorial for a bounded result

A tutorial changes the document's center of gravity. It should guide a reader from a known starting state to a result they can check, rather than expose every possible option.

Submit and verify a local event receipt

This exercise uses a local teaching server and client. It creates no external account, requires no real credential and contacts only loopback. Its goal is an accepted receipt that can be read back, not downstream event delivery.

1. Prepare an empty working folder and a supported Node runtime. Confirm the runtime before starting.
2. Download the server and client files linked from the full tutorial into that folder.
3. Start the server in one terminal and retain its listening address.
4. Run the client in a second terminal from the same folder.
5. Inspect the receipt and the client's readback check.
6. Rerun the unchanged client to observe the fixture's idempotency behavior.
7. Stop the server and confirm a subsequent client run does not report success.

If the server does not start, inspect the port and runtime rather than editing the payload. If the response is unauthorized, inspect the fixture's fake credential and headers rather than repeatedly resending unchanged requests. The full prerequisite-focused tutorial supplies commands, downloads, test evidence and teardown.

This miniature outline shows the tutorial's job; it is not a second complete set of runnable instructions. Link the maintained tutorial instead of copying all its commands into multiple pages and letting them drift apart.

Link the documents at decision points

Links should answer the question the reader has at that moment. From the use-case guide, link implementation and documented constraints. From the tutorial, link credential setup, field definitions and error recovery. From the reference, link a first-use example and the conceptual explanation when it helps.

GitHub's getting-started documentation provides a concrete primary example of explaining request components and then progressing through setup, authentication, requests and responses. Its specific headers and credentials belong to GitHub; the useful structural lesson is a connected task path.

Avoid generic related-links blocks as the only navigation. A reader who needs the exact permission requirement should not have to browse a resource index to guess where it lives.

Avoid duplication without making every page incomplete

Some repetition is useful: the product name, applicable version, critical credential boundary and meaning of success may need to appear wherever the instruction is used. Repeating a whole explanation or long tutorial across several pages creates maintenance risk.

Use a short local statement plus a specific link. For example, a request example should say that it uses a server credential and link its setup. It should not say only “use the token from above” if the section might be read independently.

Keep shared contract facts in a maintained source where practical. If the API changes a response field, update the reference and find every example that depends on it. A clear page taxonomy makes that audit easier because each page's obligation is known.

For finer editing of standalone sections, use the context-preservation guide. This article's focus is choosing and connecting page types, not imposing a fixed paragraph length.

Test each page against its own outcome

Reviewing all documentation with one checklist can hide important failures. Use a different reader test for each type:

• Give an evaluator the use-case guide and ask when the product is unsuitable.
• Give a developer the reference and ask them to identify the request fields and success meaning.
• Give a new reader the tutorial and ask them to complete the stated task from the documented starting state.

Record where the reader needs information that is absent, inconsistent or buried elsewhere. Do not count word count or headings as proof of task completion. A page with fewer sections can be more complete for its specific job.

For an AI-assisted workflow, preserve the same factual standards. A model mentioning the product is not evidence that the tutorial worked. An implementation test should check the actual result, while source visibility is a separate measurement.

Use the page decision in your content plan

When a content gap appears, specify the missing reader outcome before commissioning a page. A purchasing question may require a use-case guide or technical comparison. A field ambiguity requires reference work. A failed setup path requires a tutorial repair.

This avoids responding to every finding with another generic blog post. It also makes internal linking more intentional: the new page has a defined place in the evaluation-to-implementation path.

The API discovery guide shows how these documents support broader product evaluation. The technical comparison guide covers decisions involving multiple products. Their usefulness depends on accurate underlying reference material.

Should a reference page include examples?

Yes, when examples clarify the contract. Keep them accurate and scoped. A reference example is not automatically a complete tutorial; it may assume setup that the page should link explicitly.

Can one page serve several roles?

It can when the task is small and the structure stays clear. Split it when evaluation, explanation and implementation compete for attention or require different maintenance. The number of URLs is not the goal.

Which page should we write first?

Establish the product facts and contract, then choose the page that resolves the most important reader gap. A tutorial cannot compensate for an undefined operation, and a use-case guide should not promise behavior the reference cannot support.

Sources and review date

Sources checked September 17, 2026. Example Events is fictional; its miniature documents illustrate an editorial approach, not production-service guarantees.

• Diátaxis: distinctions among documentation needs.
• OpenAPI 3.1.1 Operation Object: pinned reference for operation contract fields.
• GitHub REST getting started: a primary example of a connected setup/request/response path.

Continue reading

• API Documentation for AI-Assisted Discovery
• Write Integration Tutorials with Clear Prerequisites
• Write Useful Technical Product Comparisons

Explore GEO with Jam

See how Jam approaches AI visibility research and content improvements for developer-tool teams.

Explore Jam for GEO