API design,
every wire format.

Why APIs matter.

A function call inside a process is a contract you can change at compile time — every caller is recompiled, every type is checked. An API call across a network is a contract you can change at most once a year, while millions of clients you do not control keep calling the version you shipped last March. That asymmetry is the whole game.

Roy Fielding's 2000 dissertation gave us REST: six architectural constraints that turn HTTP into a uniform interface. Most "REST APIs" only follow some of them, and that's usually fine — the word has drifted to mean "HTTP+JSON RPC over nouns", which is a perfectly good way to ship product. But under the surface, every successful API — REST, gRPC, GraphQL, anything — solves the same four problems: what's the shape, what's the wire, how does it evolve, and what does retry mean.

The contract outlasts the code. The Stripe API is a single date-pinned surface from 2011 to today. Twilio's older endpoints predate iPhone 4. The wire format you ship in 2026 will outlive at least three rewrites of the implementation; design the surface first, the implementation second.

Twelve mental models.

Twelve concepts cover ~95% of API surface. Get these in your bones in the first month; every API style you encounter (REST, gRPC, GraphQL, JSON-RPC, AsyncAPI) is a recombination of them.

Day zero — first hour.

One hour. Read RFC 9110 sections 9 and 15 (HTTP methods and status codes). Open Stripe's API reference. Then pick one of your own endpoints and write its OpenAPI fragment. The bar is muscle: you have read the canonical HTTP semantics and you have authored a machine-readable contract for one real endpoint.

# 1. Read RFC 9110 §9 (methods) + §15 (status codes) (≈ 30 minutes)
#    https://datatracker.ietf.org/doc/html/rfc9110

# 2. Tour Stripe's API reference (≈ 20 minutes)
#    https://stripe.com/docs/api
#    Note: <a href="/codex/distributed-systems/topics/idempotence">idempotency</a> keys, expandable objects, error codes,
#    cursor pagination, the version header.

# 3. Write OpenAPI for one endpoint you own (≈ 20 minutes)
#    Use the Swagger Editor — it lints as you type.
#    https://editor.swagger.io
openapi: 3.1.0
info: { title: Orders, version: '2024-08' }
paths:
  /v1/orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { $ref: '#/components/schemas/Order' }
        '404': { $ref: '#/components/responses/NotFound' }

# 4. Generate a client; call your real endpoint
npx @openapitools/openapi-generator-cli generate \
    -i openapi.yaml -g typescript-fetch -o ./client

Done. You have read the right two RFC sections, studied the gold-standard public API, and written a real OpenAPI doc. Everything below extends from this beachhead.

Week 1 to Month 3 — pick a track.

After the first hour you can read API design writing without bouncing off it. The next three months should be one track at a time, depth-first. Don't try to learn gRPC and GraphQL in the same fortnight; pick the one that maps to your job and finish it.

Books worth reading.

Honourable mentions: The OpenAPI Handbook (Frank Kilcommins, free); API Security in Action (Neil Madden — the only good book on API auth threat models); Designing Distributed Systems (Burns) for the platform-team operational frame.

Courses and references.

• Google · AIPs
  API Improvement Proposals
  Google's public API style guide, written as numbered design notes (AIP-122 resource names, AIP-132 standard methods, AIP-158 pagination, AIP-200 errors). The most opinionated, well-argued public API guide on the internet.
• Stripe Engineering
  API versioning at Stripe
  The blog post and follow-ups that explain date-based versioning. Read it; then read every other Stripe engineering post on idempotency, webhooks, and "expandable objects". Treat the Stripe API as the gold standard until you have shipped one bigger.
• GitHub · REST API
  REST API reference
  The other gold-standard public API. Read GitHub's pagination (link-header style — different from Stripe), conditional requests (ETag-based), and rate-limit headers. Two opinionated styles, both production-grade.
• Google · Protobuf docs
  Protocol Buffers documentation
  The Protobuf language guide and encoding spec. The encoding doc — varints, ZigZag, wire types — is forty pages and explains every binary serialisation question you'll ever have. Read it once.
• gRPC · core docs
  gRPC core concepts
  The gRPC official docs. Streaming modes, deadlines, interceptors, status codes. Pair this with the gRPC-Go README for "what does the client actually look like". Build a tiny bidi service to make it real.
• GraphQL Foundation
  Learn GraphQL
  The official tutorial. Schemas, resolvers, queries, mutations, subscriptions. Pair with the Apollo Federation docs for the multi-team flavour and Marc-André Giroux's blog for production gotchas.

• Manning
  JJ Geewax — API Design Patterns
  Geewax (Google) — the closest thing to a "design patterns" book for APIs. List operations, resource naming, custom methods, long-running operations, errors. Dense, opinionated, prescriptive. Worth every minute.

Papers worth reading.

Twelve documents — half RFCs, half engineering essays — that define modern API design. Read them in order; read each twice if you can. Most are 10–30 pages.

1. 01
   2000 · Roy Fielding

   Architectural Styles and the Design of Network-based Software Architectures (Ch. 5: REST)

   The dissertation. Chapter 5 alone is the definition of REST — six constraints, the uniform interface, hypermedia as the engine of application state. Most "REST APIs" follow about half of it; that's usually fine, but you should know which half.

2. 02
   2014 · IETF

   RFC 7230–7235 — HTTP/1.1 (revised)

   The current normative HTTP/1.1 spec, in six parts. Read 7230 (message syntax) and 7234 (caching) at minimum; everything else is reference. RFC 9110/9112 (2022) supersede most of these as the unified semantics-and-message spec.

3. 03
   2015 · Belshe, Peon, Thomson

   RFC 7540 — HTTP/2

   Binary framing, multiplexed streams, HPACK header compression, server push (now deprecated). The substrate every modern HTTPS connection rides on; the substrate gRPC was designed for.

4. 04
   2018 · IETF

   RFC 8446 — TLS 1.3

   The TLS rewrite. Forward secrecy by default, 1-RTT handshake, 0-RTT resumption with care. If your API requires a transport-security mental model, this is the floor.

5. 05
   2017 · Sambra et al

   Solid: A Platform for Decentralized Social Applications

   Tim Berners-Lee's linked-data social platform. Worth reading not for adoption (low) but for the design discipline — what an API looks like when "data ownership" is the first constraint.

6. 06
   2018 · Berjon et al

   JSON:API v1.1

   The most thoughtful prescriptive REST style spec. Resource objects, relationships, sparse fieldsets, sort/filter conventions, pagination. Even if you don't adopt JSON:API, the conventions are worth borrowing one at a time.

7. 07
   2019 · OpenAPI Initiative

   OpenAPI Specification 3.0

   The de-facto API description language. Swagger's grown-up form. If your team writes OpenAPI from day one and treats it as the contract, half the typical API problems vanish (client codegen, mock servers, contract testing).

8. 08
   2020 · IETF

   RFC 8594 — The Sunset HTTP Header

   Three pages. The right way to deprecate an endpoint. Stripe formalised this in production years before; the RFC catches up. Use it.

9. 09
   2022 · IETF

   RFC 9110 — HTTP Semantics

   The unified normative HTTP semantics doc. Replaces the patchwork of 7230–7235. Read sections 9 (methods) and 15 (status codes) and you have the canonical reference for "what does GET/PUT/POST mean" forever.

10. 10
    2023 · IETF

    RFC 9457 — Problem Details for HTTP APIs

    The right error envelope. type / title / status / detail / instance. Every API should ship this shape and a stable error code; clients should branch on the code, not the message.

11. 11
    2018 · Google

    API Improvement Proposals (AIPs)

    Google's public API style guide, written as numbered design notes. Read AIP-122 (resource names), AIP-132 (Standard methods), AIP-158 (pagination), AIP-217 (List filtering), AIP-200 (errors). Easily the most opinionated, well-argued public API guide in existence.

12. 12
    2008 · Pat Helland

    Life Beyond Distributed Transactions

    Helland's argument that everything important happens at the seams between systems — and APIs ARE those seams. Reframes idempotency, partial failure, and message-passing as architectural primitives, not implementation details.

Going further: RFC 7235 (HTTP authentication), RFC 6749 (OAuth 2.0) and RFC 7636 (PKCE), RFC 7519 (JWT), RFC 6455 (WebSocket protocol), The Twelve-Factor App (Wiggins), and the Standard Webhooks spec from Svix.

Talks worth watching.

• Pat Helland · QCon
  Life Beyond Distributed Transactions
  The seminal talk on why APIs are the seams of every distributed system. Helland reframes idempotency, partial failure, and message-passing as design primitives. Watch this before you write another retry loop.
• Stripe · Engineering
  Designing robust and predictable APIs with idempotency
  Brandur Leach on Stripe's idempotency keys. Half talk, half walk-through of the production code. The talk to watch before designing any state-mutating endpoint that touches money or external systems.
• Mark Nottingham · IETF
  HTTP semantics: a re-introduction
  Nottingham — co-chair of the HTTP working group — on what RFC 9110 actually says and why. The lecture you wish you had been given before reading the spec yourself.
• Sam Newman
  Microservices: a Deep Dive
  Newman on the operational realities of microservice APIs. Service contracts, versioning, the cost of breaking changes. Pairs with his Building Microservices book; the talk is the executive summary.
• Lee Byron · F8 2015
  Exploring GraphQL
  The original GraphQL public talk. Lee Byron explaining what Facebook actually built and why. Watch this for the "why does GraphQL exist" frame; then read Production Ready GraphQL for the "how does it survive in production" answer.

Hands-on tools.

Theory without runnable artefacts is fragile. Each of these is a tractable way to make an API design choice and watch it push back when you make a mistake.

Wire formats — side by side.

Eight formats, four properties. The size and parse columns are relative to JSON; the schema column tells you whether you can debug with cat.

Defaults: public APIs → JSON; gRPC → Protobuf; Kafka pipelines → Avro (with Schema Registry) or Protobuf; IoT / WebAuthn → CBOR; games / mmap'd files → FlatBuffers. Do not pick a binary format for a public API.

Common mistakes.

Patterns every team writes at least once. Read these now; recognise the shape later, when something on-call is misbehaving and the dashboard is unhelpful.

200 OK with {"error": "..."} in the body

The original sin. Use real status codes — 4xx for client errors, 5xx for yours, plus an RFC 9457 problem-details body. Tooling, retries, and clients all assume the status code is the truth.

Tunneling everything through POST

Verb-style URLs (POST /createUser, POST /getUser?id=42) sacrifice idempotency, cacheability, and HTTP semantics. Resources are nouns; verbs are verbs; the matrix mostly works out.

Reusing Protobuf field numbers

A renumbered field looks like its old type to old clients — silent decode corruption. Always reserve field numbers and field names after a delete: reserved 4, 7; reserved "old_field";

Offset pagination at scale

?page=1000 forces the database to scan and skip 50,000 rows. Worse, inserts during paging produce duplicates and gaps. Cursor-paginate from day one — the cursor cost is one extra opaque string.

JWT with HS256 + RS256 acceptance

If your verifier accepts both algorithms, an attacker swaps your public key into an HS256 token and forges admin tokens. Pin the algorithm. Reject alg: none always.

No idempotency on payment endpoints

Network retry → double charge. Stripe-style Idempotency-Key headers cost ~50 lines of code (key + hash table + 24h TTL) and prevent the worst class of production incidents.

Versioning by Content-Type AND URL AND custom header

Pick one strategy. Two is a smell, three is unmaintainable. The team that "supports all three for flexibility" cannot tell which one the client actually used.

Webhooks without HMAC signing

Anyone with the URL can fire fake events. Sign on raw bytes (not parsed JSON); enforce a 5-minute timestamp window; constant-time-compare. Use the Standard Webhooks header set.

Synchronous fan-out for N integrations

When checkout calls 10 webhooks inline, p99 = max(p99 of each). Move webhooks to a queue. Return to the user immediately; deliver the events with retries.

Surfacing internal IDs as sequential integers

GET /orders/12345 leaks volume and enables enumeration attacks. Use UUID/KSUID; prefix with the resource type (ord_, cus_) for grep-ability and leak-detection.

Quick test.

Ten cards covering the questions interviewers ask, the things that bite operators in production, and the trivia that separates "I write APIs" from "I design them".

Reading progressions

Three ordered paths through this material — pick the one that matches where you are.

What's next.

API design rewards re-reading. RFC 9110 read on day 30 and again on day 300 will give you different things. So will the Stripe API reference. So will Pat Helland's QCon talk. The field is not large; it is dense and citation-heavy and has been compounding since roughly 1996.

Pick one real public API and read its reference end to end. Stripe, GitHub, Twilio, AWS S3, Slack — all open and well-documented. Then re-read your own API and rewrite the parts that embarrass you. You will rewrite some.