.http files as API documentation that can't go stale

Every team has the wiki page: "How to call the orders API", written eighteen months ago, three fields out of date, top result in the internal search. API documentation goes stale because it lives apart from the code and nothing forces it to stay true.

A .http file is documentation with a forcing function. It states exactly how to call the API — method, URL, headers, body — and anyone can press Run to find out whether it's still true. It lives in the repo, so the PR that changes the endpoint is the PR that updates the docs, reviewed by the same people in the same diff.

Executable beats descriptive

Compare the failure modes. A wiki page that drifts stays silently wrong for months. A .http file that drifts fails when run — the reader discovers the drift in seconds, and the fix is a one-line edit in a normal PR. That asymmetry is the entire argument:

@baseUrl = https://localhost:7220

### Create an order
# Requires the "orders:write" scope.
# customerId must reference an existing customer.
POST {{baseUrl}}/api/orders
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "customerId": 42,
  "items": [{ "sku": "KV-100", "qty": 2 }]
}

That block is the documentation: the shape of the call, the auth it needs, the constraints that matter — and it's one keypress from proving itself.

Conventions that make a file read like docs

• One file per API area (orders.http, auth.http), living next to the code that implements it — layout argued in how to store API requests in Git.
• Named ### blocks in workflow order: reading top-to-bottom should tell the story of using the API — log in, create, fetch, update.
• # comments for the things a URL can't say: required scopes, invariants, gotchas. Comments are cheap; tribal knowledge is expensive.
• {{variables}} for everything environment-specific, so the file documents the shape while .env environments carry the values — and no secret ever lands in the docs (auth patterns).

The onboarding test

Hand a new teammate nothing but the repo. With wiki-style docs, their first successful API call is an afternoon of Slack questions. With .http files, it's: open auth.http, run the login request, open orders.http, run the first block. The examples gallery shows what well-shaped files look like; the format guide is the five-minute syntax read.

Honest boundaries — this isn't a reference generator

.http files document workflows: how a human actually calls the API, in order, with real payloads. They do not replace a generated reference — if you need every field of every schema enumerated, that's your OpenAPI spec's job, and the two compose cleanly: the spec is the dictionary, the .http files are the phrasebook. (Starting from a spec? Generate the initial files from it.) Karve itself doesn't generate documentation sites — the claim here is narrower and stronger: the runnable file is the doc.

Keeping it honest over time

Two habits close the loop:

1. Review request files like code — a PR that changes an endpoint without touching its .http block should make a reviewer ask why.
2. Run the files routinely — manually while developing (in Karve or any .http-aware editor), and in CI as smoke checks with the free CLI runners, so drift surfaces on a schedule instead of during an incident.

Documentation that runs is documentation that gets fixed.

---

Related: API testing with .http files — the same files wearing their other hat.