Good API Design

The tension that generates everything else

An API has two masters and they want opposite things. The people building it want flexibility, because they'll have to live with this interface for years. The people using it want familiarity, because the API is not their goal — it's an obstacle between them and their goal.

The second half of the tension is the one that makes APIs a distinct discipline: APIs are hard to change. You can rewrite the service behind an endpoint on a Tuesday. You cannot rename a field in its response without breaking every consumer who reads that field. That asymmetry — cheap internals, expensive interface — is why API design deserves care that most internal code does not.

Where "real REST" fits

Goedecke is dismissive of the REST purity debate: "People get wrapped up in what 'real' REST is, or whether HATEOAS is a good idea." He's largely right, but the reason is more interesting than the dismissal.

Roy Fielding coined REST in his dissertation and has been unambiguous that most things called REST are not:

"I am getting frustrated by the number of people calling any HTTP-based interface a REST API. […] That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating." […] "if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period." Roy Fielding, REST APIs must be hypertext-driven, 20 October 2008

But two days later, in his own comment thread, he conceded the point that dissolves the whole argument:

"That doesn't mean that I think everyone should design their own systems according to the REST architectural style. REST is intended for long-lived network-based applications that span multiple organizations. If you don't see a need for the constraints, then don't use them. That's fine with me as long as you don't call the result a REST API." Roy Fielding, same comment thread, 22 October 2008

So the dispute is terminological, not architectural. Fielding isn't saying your API is broken; he's saying stop calling it REST. Goedecke's practical stance and Fielding's 2008 concession are compatible.

The Richardson Maturity Model, correctly cited

You will meet the "four levels of REST" ladder — Level 0 (HTTP as an RPC tunnel), Level 1 (Resources), Level 2 (HTTP Verbs), Level 3 (Hypermedia Controls). It is a teaching heuristic, and both its originator and its populariser said so.

The uncomfortable claim: API quality is marginal

This drew zero pushback across 160 Hacker News comments and 55 Reddit comments. Nobody defended Jira's or Facebook's API. It is the least controversial claim in the essay, which is itself notable given how much effort the industry spends on API polish.

Bad products make bad APIs

# Stage 1 — the internal pointer becomes public API
GET /comments/1
→ { "id": 1, "body": "...", "next_comment_id": 2 }

# Stage 2 — worse: the whole structure, nested
GET /comments
→ { "body": "...", "next_comment": { "body": "...", "next_comment": {...} } }

# Stage 3 — the traversal cost surfaces as an async job the caller must orchestrate
POST /comments/fetch_job/1   → { "job_id": 589 }
GET  /comments_job/589      → { "status": "complete", "comments": [...] }

His diagnosis is exactly right: "Technical constraints that can be cleverly hidden in the UI are laid bare in the API, forcing API consumers to understand far more of the system design than they should reasonably have to."

The move that unblocks awkward operations

The most useful idea in the discourse wasn't in the essay. A long Reddit sub-thread argued that resource-oriented design fundamentally cannot express transactions — that you inevitably end up with "a billion endpoints for every imaginable usecase."

Two replies reframed it: "you're missing an axiom… (REST) APIs should be atomic. If you're doing complex transactional stuff, it's probably the wrong paradigm" (u/XtremeGoose), and more bluntly, "You gotta stop thinking the API is a database, man" (u/utdconsq). The resolution the original poster accepted:

// Awkward: an RPC verb wearing a REST costume. No handle, no status,
// no retry story, no audit trail.
POST /accounts/42/close_and_refund_and_notify

// Better: the operation is a thing that exists, and can be inspected.
POST /account-closures
  { "account": "42", "refund": true, "notify": true }
→ 202 { "id": "clo_9f2", "state": "pending", "account": "42" }

GET  /account-closures/clo_9f2   // status, failure reason, partial progress
GET  /account-closures?state=failed

Fielding got there in 2008 from the opposite direction: "If you find yourself in need of a batch operation, then most likely you just haven't defined enough resources." A Reddit thread in 2025 reinvented it independently. That convergence is a good sign you should trust the pattern.

Naming: pick a convention, then stop thinking about it

Goedecke says nothing about naming, which is consistent with his thesis — naming is exactly the kind of thing that generates enormous discussion and very little value, as long as you are consistent. Inconsistency is the actual defect. Zalando's guidelines, one of the two most complete public style guides, fix all three casings so nobody has to argue:

Their stated reason for snake_case is pure familiarity, which is Goedecke's own argument: "many popular Internet companies prefer snake_case: e.g. GitHub, Stack Exchange, Twitter." Google's AIPs choose differently (lowerCamelCase in JSON). Both are fine. Picking neither is not.

The missing half

The top-voted comment in the entire Hacker News thread does not disagree with him. It completes him, and it's the most useful sentence in the discourse:

The change classification you should steal

GitHub publishes the clearest list, and it is worth internalising because roughly half of these surprise people:

Tolerant reader — the discipline that makes additive changes safe

Goedecke's "consumers should ignore unexpected fields" is Postel's Law, and Zalando operationalises it into rules you can put in a code review checklist:

The PUT clause in #108 is the subtle one. A client that strips unknown fields on read and then PUTs the object back will silently delete data it never understood. That's a data-loss bug caused by an additive change — the API owner did nothing wrong and the customer is still down.

This attracted roughly 60% of all comments across both threads, and the critics did not agree with each other — which is the best evidence that this is a genuine tradeoff and not a solved problem.

Now make the calls yourself

Reading about a versioning tradeoff is not the same as making one. Below is a simulator. It gives you five change requests of the kind that actually land on an API owner's desk, and it will not let you see any consequence until you have committed to a decision and written down why.

It is not a quiz — several options are defensible and the reveal shows you what every option would have done, not just yours. But it keeps a debt ledger. Choices that avoid a break by carrying something forever accumulate there, and in the fifth scenario the bill comes due, scaled to what you actually accrued. That second-order effect is the part the essay leaves out.

What the published schemes actually do

Where Goedecke's cost model actually breaks down

"Thirty endpoints × N versions" is the strongest-sounding part of his argument and the weakest part under inspection, because nobody serious versions that way. Stripe's model is neither per-endpoint nor per-API — it is per-change, composed. A "version" is just a date that selects how many transformation modules to replay:

// One module per breaking change, ever. Not per endpoint, not per version.
const changes = [
  { since: "2024-09-30", downgrade(res) { res.amount_cents = res.amount * 100 } },
  { since: "2025-03-31", downgrade(res) { res.customer = res.customer.id } },
  // ...~100 of these, accumulated since 2011
];

// Serving an old client = replay the modules newer than their pinned date, backwards.
function serialize(res, clientVersion) {
  return changes
    .filter(c => c.since > clientVersion)
    .reverse()
    .reduce((r, c) => (c.downgrade(r), r), res);
}

Cost scales with the number of breaking changes you have ever made, not with endpoints × versions. That dissolves his arithmetic — but it does not dissolve his conclusion, because that machinery is expensive to build, and Brandur Leach's own account concedes the leak Goedecke cites. His cost claim is validated. His inference from it is not the one Stripe drew.

RFC 9457, Problem Details for HTTP APIs

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type":     "https://example.com/probs/insufficient-funds",
  "title":    "You do not have enough credit.",
  "status":   403,
  "detail":   "Your balance is 30, but the transfer costs 50.",
  "instance": "/account/12345/transactions/msg-abc",

  // extension members are allowed and encouraged
  "balance":  30,
  "accounts": ["/account/12345"]
}

The stable-taxonomy pattern

Twilio is the model, and it's the most Goedecke-compatible thing in this course: four fields, a numeric code that has meant the same thing for a decade, and a documentation URL per code.

{
  "status":    400,
  "message":   "No to number is specified",
  "code":      21201,
  "more_info": "http://www.twilio.com/docs/errors/21201"
}

The full numeric dictionary is published and downloadable as JSON, with a page per code. That is what "boring" looks like when someone actually does it.

The performance claim, verified

-- Offset: the database counts past every skipped row, every time.
SELECT * FROM tickets ORDER BY id OFFSET 5000000 LIMIT 10;

-- Keyset: the index seeks straight to the position. Cost is flat.
SELECT * FROM tickets WHERE id > :cursor ORDER BY id LIMIT 10;

-- Real cursors need a tie-breaker, or rows with equal sort keys are
-- skipped or duplicated. This is the part people get wrong.
SELECT * FROM tickets
 WHERE (created_at, id) > (:c_ts, :c_id)   -- row-value comparison
 ORDER BY created_at, id LIMIT 10;

What cursors cost you — from cursor advocates

Correction one: PUT and DELETE are already idempotent

He published a correction acknowledging he should have mentioned PUT. The implication is bigger than the correction.

Why this reframes the whole chapter: if PUT is idempotent for free, then the entire Idempotency-Key apparatus is only needed for POST and PATCH. A client-generated resource id plus PUT /transfers/{client_uuid} gets you safe retries with no extra machinery at all. Reach for the header when you genuinely need POST semantics — not by default.

Correction two: Redis is not enough

He also published a correction on storage, prompted by the sharpest technical comment in the thread:

"I'm not sure how storing a key in Redis achieves idempotency in all failure cases… Can't assume that the comment had been created before, since the process could have been killed in-between storing the key in Redis and actually creating the comment in the database. An attempt to store idempotency key needs to be atomically committed… together with the operation payload… For all intents and purposes, the idempotency key is the ID of the operation being executed."HN achernik

// BROKEN — two systems, no shared transaction. Crash anywhere between
// them and you cannot tell "already done" from "never started".
if (await redis.set(key, 1, "NX")) {   // <-- crash here...
  await db.comments.insert(payload);   // ...and this never runs, forever
}

// CORRECT — the key and the effect commit together, or neither does.
await db.transaction(async (tx) => {
  const claimed = await tx.idempotency_keys
    .insert({ key, request_hash })
    .onConflictDoNothing();
  if (!claimed) return tx.idempotency_keys.get(key).response;
  const comment = await tx.comments.insert(payload);
  await tx.idempotency_keys.setResponse(key, comment);
  return comment;
});

The three-state machine, and the status codes

The data that should settle it — and doesn't

Rate limits: an API is a UI with no hands

That last clause is the non-obvious one and it's correct: telling clients their budget lets you give them a smaller budget. A client that can see it has 12 calls left will back off. A client flying blind will hammer you and then complain.

The two headers

HTTP/1.1 200 OK
Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 UTC
Link: <https://api.example.com/docs/migrating-to-v2>; rel="deprecation"; type="text/html"

Both RFCs are careful to say these are hints, not contracts: "Clients SHOULD treat Sunset timestamps as hints," and "The act of deprecation does not change any behavior of the resource." A header is not a migration plan — it is a machine-readable channel for one.

Deprecation as a process, not an announcement

Zalando publishes the most complete public deprecation regime, and the striking thing is how much of it is about consent and observation rather than notification:

#186 is the clever one: partners agree to the after-deprecation lifespan as a condition of access, before they've written a line of code. That converts an eventual argument into a precondition. #188 is the operationally essential one — if you cannot see who is still calling the old thing, your sunset date is a guess.

What deferral actually costs

The counter-example is real and worth respecting: Twilio has served api.twilio.com/2010-04-01/ for about sixteen years. Its one predecessor, 2008-04-01, was deprecated in May 2022 and hard-404'd on 15 December 2023 — roughly twenty months of notice, two versions in eighteen years. It can be done. Note, though, that they enforce it by blog post: no evidence was found that Twilio emits Sunset or Deprecation headers at all.

Optional fields first

Before GraphQL, Goedecke offers the cheap version of the same idea, and it's good advice: "If parts of your API response are expensive to serve, make them optional.… you could have an includes array parameter with all your optional fields."

GET /users/42
GET /users/42?include=subscription,posts
// Default response stays small and fast. Expensive joins are opt-in.
// Still one cacheable URL per resource. Still readable in a browser bar.

Internal APIs: less different than he says

The synthesis: developer experience is the through-line

Everything in this course is one argument in different clothes. The cost of your API is paid by people who are not thinking about your API.