DEV Community

Cover image for How to Explain One API Endpoint With a Single Worked Request
explain.ink
explain.ink

Posted on

How to Explain One API Endpoint With a Single Worked Request

Open almost any API reference and you will find the same layout: the method and path, a table of parameters, a table of response fields, and a list of error codes. All of it is correct, and a developer seeing the endpoint for the first time still has to assemble it in their head before they can make a call.

Five sequential steps: Choose the most common call, Write copyable request, Show complete response, Connect the two, and Show the error people...

What helps most is one worked request: a complete call a reader can copy, the complete response it returns, and a few sentences that connect the two. This article shows how to build that example for one endpoint and where the reference tables still belong.

The API in the examples is invented: a small task tracker with a POST /tasks endpoint. The shape applies to any endpoint.

Why a table is not enough

A parameter table answers "what can I send". A new reader is asking a different question: "what do I send to get what I want". To answer it from a table, they have to pick the required fields, guess sensible values for them, work out the format of each, and imagine the response. Every one of those steps is a chance to get it wrong.

A worked request does those steps for them once, with real values, and shows the result. The table then becomes the place they go to change something, not the place they start.

Step 1: choose the most common call

Do not show the call that uses every option. Show the call most people make first. For POST /tasks that is creating a task with a title and an assignee, not a task with labels, attachments, a parent and a custom field.

If you are not sure which call is the most common, look at your support questions or your logs. Write down the one request a new user makes in their first hour.

Step 2: write the request so it can be copied

curl -X POST https://api.example.com/v1/tasks \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Renew the TLS certificate",
    "assignee_id": "usr_2841",
    "due_date": "2026-12-01"
  }'
Enter fullscreen mode Exit fullscreen mode

Allowed and not allowed patterns for request fields: using $API_TOKEN versus real tokens, realistic values like "Renew the TLS certificate" versus...

A few details make the difference between an example people copy and one they rewrite:

  • The token comes from an environment variable, so the command works as soon as the reader has set it, and nobody pastes a real token into a ticket.
  • Values look real. "title": "string" teaches nothing; "Renew the TLS certificate" shows what a title is for.
  • Formats are visible. The date in due_date shows the expected format without a separate sentence.
  • Only the fields this call needs. Optional fields belong in the table.

Step 3: show the complete response

{
  "id": "tsk_90317",
  "title": "Renew the TLS certificate",
  "status": "open",
  "assignee_id": "usr_2841",
  "due_date": "2026-12-01",
  "created_at": "2026-11-17T15:02:44Z"
}
Enter fullscreen mode Exit fullscreen mode

Show it whole, or say clearly where you cut it. Readers use the response to answer their next question: what do I store, what do I pass to the next call. Here the answer is visible: the id, which is what every later call about this task needs.

Step 4: connect the two in a few sentences

Under the example, explain only what the reader cannot see:

The new task starts with status: "open". Keep the returned id: you need it to update or close the task. due_date is optional; without it the task has no deadline.

Three sentences. They name the field that matters for the next step, the default the server filled in, and the one optional field in the example. Everything else is already obvious from the request and the response.

Step 5: show the error people actually hit

One error example is worth adding: the one that happens most often for new users. For this endpoint, it might be a missing title:

{
  "error": "validation_failed",
  "message": "title is required",
  "field": "title"
}
Enter fullscreen mode Exit fullscreen mode

Say what causes it and what to change. A reader who hits it will search the page for the message text, so use the exact text the API returns.

Where the tables go

The reference tables still matter. Put them after the worked example, and treat them as the place for completeness:

Field Type Required Notes
title string yes Up to 200 characters
assignee_id string no A user id, usr_...
due_date date no YYYY-MM-DD

Readers come back to the table when they want to do something the example does not show. Because they already made one successful call, they read the table with a working mental model instead of building one from it.

A short checklist

  • The example is the most common first call, not the fullest.
  • It runs as copied once the reader sets one variable.
  • Values are realistic and show their formats.
  • The response is complete or the cut is marked.
  • Two or three sentences point at what the reader needs for the next call.
  • The most common error is shown with its exact message.
  • Tables come after the example.

Where this does not help

Endpoints whose behaviour depends heavily on state (a search with many filters, a webhook that fires on events) need more than one example. Show two or three short ones for distinct cases rather than one long one.

Generated reference documentation from an OpenAPI file cannot write the connecting sentences for you. The worked request and its explanation are written by someone who knows which field matters next.

And if your most common call needs eight fields to work, the documentation is showing you a design question about the endpoint, not a writing problem.

Pick the call a new user makes first, run it for real, and write the page around that one request.

Written with the help of AI and checked by the explain.ink team.

Top comments (0)