Valid is only the beginning

An example copied from a schema can be syntactically correct and still teach nothing. string, 123 and foo satisfy many validators, but they hide domain meaning. A good example gives the reader enough context to understand why the request exists and what successful output enables.

Use realistic identifiers and values while avoiding real secrets or personal data.

Build a small narrative

Prefer a sequence that mirrors an actual developer task: create a resource, retrieve it, update it, then handle a failure or cleanup step. Reuse identifiers across the sequence so readers can see relationships.

For standalone reference pages, link each operation to the relevant workflow instead of duplicating a giant tutorial under every endpoint.

Show the response that matters

Do not stop at the request. Include the important response headers, status code and body. Point out fields whose meaning is not obvious. If an operation is asynchronous, show how the client learns that work is complete.

Error examples deserve the same care. A realistic validation error often teaches the API faster than another happy path.

Keep examples executable

Where possible, run requests in CI against a stable test environment or validate payloads against schemas. Store code samples as files or generated snippets rather than hand-copying the same example into several pages.

When a sample cannot be executed automatically, document what was verified and when.

Optimize for transfer

The reader should be able to adapt an example, not merely paste it. Explain the one or two variables they are expected to change and the assumptions that must remain true.

The goal of an API example is a useful mental model. If the example does not make the next request easier to design, it is probably decoration.

Applied example

Turn “API examples should teach a workflow, not decorate a reference page” into one complete developer task. Use a fictional but realistic resource, such as a report, device or order, and write the shortest path from authentication to a successful result. Include the request, the important response fields, one likely failure and the next action after that failure. The exercise should be executable in principle even if the article does not depend on a live service.

Check the example as if you were building a client from it:

  • Which values must the developer replace?
  • Which identifiers are returned by the server and reused later?
  • What status or field tells the client that the operation succeeded?
  • What should the client do when credentials, input or rate limits fail?

If those answers are scattered across unrelated pages, the documentation may be technically complete but operationally weak. API documentation is successful when a developer can predict the interaction, not merely recognize endpoint names.

Quick editorial checklist

  • Valid is only the beginning. An example copied from a schema can be syntactically correct and still teach nothing.
  • Build a small narrative. Prefer a sequence that mirrors an actual developer task: create a resource, retrieve it, update it, then handle a failure or cleanup step.
  • Show the response that matters. Do not stop at the request.
  • Keep examples executable. Where possible, run requests in CI against a stable test environment or validate payloads against schemas.