Skip to content

About

The flagship reference site for modern, authoritative API design patterns.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

apiguide.dev

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 errors collection

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.

What is in it

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).

Running it locally

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

Content checks

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 factcheck

Contributing

Corrections 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.

Licence

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.

About

The flagship reference site for modern, authoritative API design patterns.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages