API and Reference Documentation: Paths, Schemas, Errors, and Edge Cases

LESSON

Clear Technical Writing, Rhetoric, and Explanation

007 30 min beginner

API and Reference Documentation: Paths, Schemas, Errors, and Edge Cases

By the end of this lesson, you will be able to...

Design an endpoint reference around the exact task a reader must complete.

Review a request schema, example, error table, and edge-case note for findability and actionability.

Explain why a successful response and a completed operation are sometimes different promises.

Idea in one sentence: A useful API reference lets a reader find one valid path, understand its limits, and recover from a likely failure without reading the whole page.

Core Insight

Mina is adding a daily file import to her team's service. She already knows that an API is available. What she needs now is smaller and more urgent: the exact path, the required fields, one request that is valid, and what to do when the server rejects her file.

Instead, the page opens with three paragraphs about the import product. Far below, it lists a JSON object with fifteen fields. It says that the endpoint can return errors. It does not say which error appears when the server cannot reach the file or whether a 202 Accepted response means that the import has finished.

All of those facts may be correct. The page still fails Mina's reader job: she cannot form a safe request or diagnose the first believable failure.

Reference documentation is an information interface. Its promise is not that a reader will enjoy reading it from top to bottom. Its promise is that, under a narrow question, the reader can retrieve the right fact and make the next safe decision. For an endpoint, that usually means finding a route, constructing a request, interpreting a response, and handling a boundary.

The Promise We Need to Keep

Imagine a fictional Parcel API. Mina must ask it to import a CSV file from a storage URL. A well-designed endpoint reference should let her answer these questions in roughly this order:

Which method and path create an import?
Which request fields are required, and what constraints do they carry?
What does one valid request look like?
Does the immediate response mean queued, running, or completed?
What should she change after a likely error?
Which unusual cases can change the result of a retry?

That order is a reader route. It is not the only possible page order, but it reflects Mina's task. A tutorial can spend time building a complete integration. An explanation can discuss why imports are asynchronous. A reference page should keep those jobs available through links while making the lookup path easy to scan.

Plain meaning:

Put the fact nearest to the decision it enables.

In Mina's situation:

She needs the POST path before a history of file imports, and she needs the meaning of 202 before a long list of optional filters.

Technical name:

This is a retrieval-first reference design. The headings, tables, examples, and notices are arranged for a short, specific lookup rather than for linear reading.

The Naive Design

A tempting design is to generate a page directly from a schema. It may contain every field name, type, and endpoint. This is better than hiding the schema, but it leaves the reader to assemble the important parts alone.

Design	What Mina gets quickly	What she still has to infer
Endpoint name plus raw schema	Names and types	Which fields make a valid request; which values are safe; how success changes state
Long integration tutorial	A full happy-path story	The exact field or error when she returns later with one question
Retrieval-first endpoint reference	A path, constraints, working example, response, errors, and edges	Broader product rationale, which belongs in linked explanation

The raw-schema page fails at the transition from field list to valid use. The tutorial fails when Mina returns next month looking only for source_url. The retrieval-first page chooses a narrower promise: it is a dependable map for one operation.

This does not mean every endpoint needs a giant page. It means a reference must reveal the constraints that change the reader's next action.

A Better Boundary: One Endpoint, One Reader Route

Here is the start of the Parcel API reference Mina needs.

Create an import

POST /v1/imports

Creates an asynchronous import from a CSV file. The response confirms that the service accepted the request for processing; it does not confirm that all rows were imported.

Field	Required	Type	Constraint and reader decision
`source_url`	Yes	string	An `https` URL that the import service can reach. Use a signed URL when the file is private.
`format`	Yes	string	Must be `csv`. The service does not infer the format in this version.
`idempotency_key`	Yes	string	Reuse the same key only when retrying the same request body. Generate a new key for a new import.
`has_header_row`	No	boolean	Defaults to `true`. Set `false` when the first row is data.

The table does more than translate JSON into prose. It joins each field to a decision. The type string does not tell Mina that a private storage URL will fail unless it is reachable by the service. The required marker does not tell her when a key may be reused. Those constraints are the actual contract she needs.

Valid request

POST /v1/imports
Content-Type: application/json

{
  "source_url": "https://files.example.net/acme/orders-2026-07-20.csv",
  "format": "csv",
  "idempotency_key": "orders-2026-07-20-a",
  "has_header_row": true
}

Accepted response

{
  "import_id": "imp_7e3",
  "status": "queued"
}

The example is not decoration. It lets Mina compare a real request against her own. It also makes the response promise visible: queued is an intermediate state, not a finished import.

A Worked Lookup: From Request to Recovery

Now trace one realistic path. Mina submits the request above, but her storage URL requires a cookie from her browser. The import service cannot send that cookie.

Step	What Mina sends or sees	What the reference must help her decide
Input	`POST /v1/imports` with `source_url` and a new key	Does the path and body match the endpoint contract?
Transition	The API accepts the request and creates `imp_7e3`	The request was accepted for background work; it is not complete.
Intermediate state	A worker tries to fetch `source_url`	The worker, not Mina's browser, must be able to reach the file.
Output	The import later reports `source_unreachable`	Make a reachable signed URL, then retry the same intended import according to the idempotency rule.
Naive failure	“The endpoint returned `202`, so the CSV was imported.”	`202` only promises acceptance for processing; inspect the import status before claiming success.

The reference needs an error table beside this route. An error name alone is not enough. A useful entry tells Mina what condition caused it and what change she should make.

Status and code	Meaning	Next action
`400 invalid_request`	A required field is absent or has the wrong shape.	Compare the request with the field table and valid example. Do not retry unchanged.
`422 source_unreachable`	The worker cannot fetch `source_url`.	Provide a reachable `https` or signed URL; then create or retry the intended import as documented.
`409 idempotency_conflict`	An existing key was used with a different request body.	Use the original body for a retry, or choose a new key for a genuinely new import.
`429 rate_limited`	The service is temporarily refusing more import requests.	Wait for the documented delay before retrying; do not create a burst of new keys.

So far, we have a full reader path: input, accepted state, background transition, later result, and a decision after failure. This matters because the reference has converted a vague “check the errors” instruction into observable choices.

Check: A page lists POST /v1/imports, every JSON field, and an HTTP 202 response, but has no example or status explanation. What is the most important addition for Mina's first request?

Think first, then reveal.

Answer: Add one valid request and explain that 202 means queued rather than completed. The fields alone do not show a usable body, and the status meaning prevents Mina from treating acceptance as completed work.

Edge Cases Are Part of the Contract

Writers sometimes treat edge cases as an appendix for readers who enjoy pain. In a reference page, an edge case belongs near the normal route when it changes the normal reader's decision.

The import endpoint has two such cases:

A retry after uncertainty. Mina times out while waiting for the 202 response. She does not know whether the server received the request. Reusing the same idempotency_key with the same body lets the service recognize a retry instead of creating a second import.
A changed retry. Mina changes source_url but keeps the old key. That is not a retry of the same operation. The service returns 409 idempotency_conflict so one identifier cannot silently mean two different imports.

The exact storage and lifetime rules vary by API. The writing principle is stable: document the condition, the visible signal, and the safe next action. Do not make a reader infer retry safety from an endpoint's name.

Check: Where should the idempotency note appear?

Think first, then reveal.

Answer: Put the short rule in the idempotency_key field row, show the key in the valid example, and add the conflict case in the error table or edge-case note. Each placement answers a different lookup: construction, imitation, and diagnosis.

Trade-offs and Limits

Retrieval-first structure improves speed and reduces accidental misuse. The central trade-off is speed for the reader versus space and maintenance for the writer. A field table, example, response note, error table, and edge-case rule can drift apart if they are updated by different people.

It also does not replace the other documentation types. A reference page should not hide a ten-step onboarding flow inside a note, and it should not attempt to justify every product decision. Link a tutorial for first setup and an explanation for asynchronous processing. The boundary appears when a reader's question changes from “what do I send?” to “why does this system work this way?”

The operational signal is reader behavior. If support requests repeatedly ask whether 202 means success, the promise is not visible enough. If readers can find the error code but still ask what to do, the table names a symptom without enabling a decision. These are documentation failures, not merely user mistakes.

Design Review: Can Mina Complete the Task?

Review an endpoint reference in the order a reader will use it:

Can the reader find the method and path without scanning product history?
Can they build a valid body from a field table whose constraints name decisions, not just types?
Can they compare their body with a plausible, complete example?
Can they distinguish immediate acceptance from completed work?
Can they map a likely error to a concrete next action?
Can they find edge cases that change retry, state, or ownership behavior?

This review does not demand that every possible failure fit on one page. It demands that the chosen boundary be honest. If the detail is too large, split it into a linked status-resource reference or troubleshooting page. Do not solve findability by placing an entire product manual under one endpoint heading.

Practice

Choose a POST endpoint from a service you know, or use this small one: POST /v1/exports. Its job is to prepare a downloadable CSV. Draft a reference section that a reader can use after a month away from the project.

Include a method and path, a field table with two required fields and one constraint, one valid request, the meaning of the immediate response, two errors with next actions, and one edge case about retry or completion. Then ask a colleague, or your future self after ten minutes, to answer: “Can I create it? What happened? What do I do now?”

A good answer should make the reader able to:

point to the exact route and request shape;
tell queued work from completed work;
change a request after one named error instead of retrying blindly; and
state what must stay the same for a retry to remain the same operation.

Resources

[REFERENCE] Google Cloud API Design Guide — Focus: Follow the links to standard methods, errors, inline API documentation, and compatibility guidance.
[DOC] Google developer documentation style: code in text — Focus: See consistent treatment of method names, parameters, and HTTP status codes in explanatory prose.
[ARTICLE] Google Cloud: What is idempotency? — Focus: Compare a safe retry with a second, distinct operation and note why an idempotency key needs a documented contract.
[DOC] Google developer documentation style: procedures — Focus: Use it when a reader must act, and keep a reference page from becoming an unscannable multi-path procedure.

Key Takeaways

A reference page serves a retrieval task: route, valid request, response meaning, error decision, and edge case.
A schema becomes usable when field constraints tell the reader what to do, not only what type a value has.
A working example and an intermediate-state explanation prevent a successful HTTP response from being mistaken for completed work.
Error entries should pair a visible condition with a safe next action.
Put an edge case near the normal path when it changes how a reader retries, interprets state, or assigns responsibility.

← Back to Clear Technical Writing, Rhetoric, and Explanation

← Back to Humanities And Philosophy

← Back to Learning Hub