A language-agnostic reference for designing HTTP APIs.
apiguide.dev catalogues the things you look up while building or integrating an API: what a status code actually means and when to send it, what a header is for, whether a method is safe or idempotent, how a specification format works, which tool does what, and long-form guides on the patterns that span all of them.
It is deliberately not tied to a language or a framework. Examples are HTTP.
The one part worth explaining, because it is useful from outside this site.
Every entry in /errors/ has a stable URL, and those URLs are designed to be
used directly as the type member of an RFC 9457
problem response:
{
"type": "https://apiguide.dev/errors/insufficient-funds",
"title": "Insufficient Funds",
"status": 402,
"detail": "The account balance is 4.20 GBP, and the transfer is 10.00 GBP."
}RFC 9457 asks that type be a URI that, when dereferenced, gives human-readable
documentation. Most APIs either invent a URI that resolves to nothing or skip
the member. This is somewhere to point instead, without hosting a documentation
page per error yourself.
Which means these URLs are a contract. They do not get renamed.
| Section | Pages | What it covers |
|---|---|---|
| Status codes | 63 | Every code, what it means, when to use it, how it compares to its neighbours |
| Headers | 118 | Request and response headers, standard and otherwise |
| Guides | 57 | Long-form patterns, in eight categories from resource design to agent readiness |
| Tools | 69 | Design, SDK generation, testing, security testing, clients, gateways, webhooks and observability |
| Errors | 55 | Resolvable problem types for RFC 9457, deferring to IANA where a type is registered |
| Specifications | 56 | OpenAPI, AsyncAPI, JSON Schema, Arazzo, gRPC and the rest |
| Methods | 19 | Semantics, safety, idempotency, cacheability |
Plus /problem-json, an
/llms.txt index of the whole catalogue and
/llms-full.txt with all of it. Every
page is also served as Markdown at its URL plus .md, every problem type as
JSON at /errors/<name>.json (with the catalogue at
/errors/index.json, in the
errors CLI format), and
/.well-known/api-catalog
points to them (RFC 9727).
Astro on bun, Tailwind v4, deployed to Cloudflare Pages.
Use bun rather than npm; Cloudflare builds from bun.lock.
bun install
bun run dev| Command | Action |
|---|---|
bun install |
Install dependencies |
bun run dev |
Dev server on localhost:4321 |
bun run build |
Build to ./dist/ |
bun run preview |
Preview the build with Astro |
bun run worker:dev |
Serve the build as production does, with the Worker and _headers |
bun run deploy |
Deploy to Cloudflare Workers |
These check whether the content is still true, rather than whether it
builds. Only factcheck needs a model: it runs
Claude Code headless, signed in, or
FACTCHECK_BIN pointing at it. Each exits non-zero when it could not run, so a
silent pass means a real pass.
| Command | Action |
|---|---|
bun run check:internal-links |
Confirm every internal link in the build resolves. Needs a build, no network |
bun run check:links |
Confirm external URLs in frontmatter still resolve. Exits 1 on a dead link |
bun run check:quotes |
Confirm text quoted from an RFC is really in it. Exits 1 on a quotation not found |
bun run check:facts |
Compare frontmatter and citations with IANA and the RFCs, with no model. Exits 1 on a mismatch |
bun run check:gaps |
Diff the catalogue against the IANA registries. Lists entries not yet documented or deliberately omitted in scripts/gaps-ignore.json; exits 2 if a registry cannot be read |
bun run factcheck |
Fact-check changed pages against primary sources. Exits 1 on findings and 2 if a page could not be checked |
bun run factcheck defaults to files changed against HEAD~1, and takes an
explicit collection/slug or path:
bun run factcheck -- methods/trace
bun run factcheck -- errors
FACTCHECK_BASE=origin/main bun run factcheckCorrections are welcome, particularly to anything that has gone out of date: a standard that moved, a tool that changed its pricing model, a header that got registered.
Content lives in src/content/<collection>/ as Markdown with frontmatter,
validated by zod in src/content.config.ts. The build fails on a schema
violation, so bun run build will tell you if the frontmatter is wrong.
Read AGENTS.md before writing a page. Each collection has a
fixed structure that every existing page follows, and it documents the shapes,
the cross-linking conventions, the voice and the spelling. It is written for
agents and is just as useful to a person. DESIGN.md covers the
palette and why it is what it is.
Two licences, because the code and the prose want different things.
- Code is MIT. Templates, components, styles, configuration
and the scripts in
scripts/. - Content is CC BY-SA 4.0. Everything under
src/content/: all 437 pages. Reuse it, translate it, build on it, with credit and under the same terms.
Linking to a page here is not use of the content and needs no licence. Using
https://apiguide.dev/errors/<name> as the type member of an RFC 9457
problem response is what those URLs exist for.