How to Document a REST API Endpoint (With a Worked Example)

An API that works perfectly but has no documentation might as well not exist to the people trying to integrate with it. Good endpoint documentation turns a guessing game into a copy-paste-and-go experience. This guide covers exactly what to include when documenting a REST endpoint, walks through a full worked example, and explains when plain Markdown docs are enough versus when you need a formal OpenAPI spec.

Why Undocumented APIs Cause Real Friction

When an endpoint isn't documented, every consumer of your API has to reverse-engineer it — reading source code, guessing at field names, or opening a support ticket. That friction shows up in predictable, expensive ways:

• Support load — "what fields does this endpoint expect?" becomes a recurring Slack message or ticket instead of a five-second doc lookup
• Slower integrations — partner teams or external developers spend hours on trial-and-error requests instead of minutes reading a page
• Onboarding pain — new engineers on your own team waste their first week tracing controller code just to understand what the API surface looks like
• Silent breaking changes — without documented request/response shapes, nobody notices when a field quietly changes type or gets removed

What to Include for Every Endpoint

• Method and path — e.g. POST /api/orders — the single most scanned line on the page
• Description — one or two sentences on what the endpoint does and any side effects (does it send an email? charge a card?)
• Path parameters — any {id}-style segments in the URL, with type and meaning
• Query parameters — filters, pagination (page, limit), sorting — marked required or optional with defaults
• Request body — a realistic JSON example, with each field's type and whether it is required
• Response example — a realistic JSON example of a successful response, matching real field names exactly
• Status codes — every code the endpoint can actually return, and what triggers each one

Worked Example: Documenting POST /api/orders

Let's document a realistic order-creation endpoint from scratch, section by section.

Method, path, and description

## POST /api/orders

Creates a new order for the authenticated user. On success, this also
triggers a confirmation email and reserves stock for each line item.

Request body

### Request Body

| Field       | Type   | Required | Description                        |
|-------------|--------|----------|-------------------------------------|
| customer_id | string | yes      | ID of the customer placing the order|
| items       | array  | yes      | List of { product_id, quantity }    |
| coupon_code | string | no       | Optional discount code              |

{
  "customer_id": "cus_8821",
  "items": [
    { "product_id": "prod_101", "quantity": 2 },
    { "product_id": "prod_205", "quantity": 1 }
  ],
  "coupon_code": "WELCOME10"
}

Response example

### Response — 201 Created

{
  "order_id": "ord_5510",
  "status": "pending",
  "total_amount": 1899.00,
  "currency": "INR",
  "created_at": "2026-07-12T09:15:00Z"
}

Status codes

### Status Codes

201  Created        — order created successfully
400  Bad Request     — missing or invalid fields in the request body
401  Unauthorized    — missing or expired auth token
404  Not Found       — one or more product_id values do not exist
409  Conflict        — insufficient stock for one or more items
500  Server Error    — unexpected failure, safe to retry

Notice this covers not just the happy path but the failure modes too — a 409 for out-of-stock items is exactly the kind of thing a consumer needs to know about before they hit it in production and file a confused support ticket.

Human-Readable Docs vs Machine-Readable Specs

There are two different jobs documentation can do, and they call for different formats.

• Markdown/README-style docs — written for humans to read directly. Fast to write, easy to review in a pull request, and perfect for internal APIs, small projects, or a `/docs` folder that ships alongside your code.
• OpenAPI/Swagger specs — a structured JSON or YAML file describing every endpoint, schema, and status code in a machine-readable format. This unlocks interactive "try it" consoles (Swagger UI), auto-generated client SDKs, contract testing, and mock servers generated straight from the spec.

A rule of thumb: start with Markdown docs. They cost almost nothing to write and cover 90% of real-world needs. Move to OpenAPI once external partners need to generate client code automatically, or once your API surface is large enough that manual docs drift out of sync faster than anyone can fix them.

Keeping Docs in Sync With the Actual API

• Update docs in the same PR as the code change — if a field is renamed, the doc update belongs in that commit, not a follow-up task that never happens
• Use real response examples — copy actual output from a request instead of hand-typing a "plausible-looking" JSON blob that drifts from reality
• Review docs in code review — treat an outdated example the same as a failing test: block the merge until it's fixed
• Add a "last updated" note — even a simple date stamp helps readers judge whether they can trust what they're reading
• Automate where you can — generating docs from code comments or an OpenAPI spec removes the chance of manual docs silently going stale

Frequently Asked Questions