Short version for the impatient: the four API design rules I actually enforce are stable error shapes, cursor pagination, idempotency keys on anything that charges money, and additive-only changes. Everything else I’ve written down over the years turned out to be preference dressed up as principle.<\/p>\n
I know this because I spent a good chunk of last month reviewing an API a client’s team had built, and I kept writing the same four comments. By the fourth PR I copy-pasted them. By the sixth I felt like a bot. So I wrote them down properly, with the reasoning, and now I paste a link instead.<\/p>\n
What follows is that document. It’s opinionated, it’s short, and I’ve been wrong about at least one of these before.<\/p>\n
The single worst thing about the API I was reviewing wasn’t that the errors were bad. It’s that there were four different kinds of bad. Validation failures came back as Every client that talked to this API had a little pile of if-statements to figure out which shape it just got. That pile is the actual cost. Not the ugliness.<\/p>\n There’s a standard for this and almost nobody uses it, which I find mildly infuriating. RFC 9457, Problem Details for HTTP APIs<\/a>, was published in July 2023 and obsoletes RFC 7807 from 2016. It defines a JSON object with five members: Here’s what the old validation error looked like:<\/p>\n And here’s the same failure as a problem document:<\/p>\n The bit that earns its keep is One practical warning from the security section of the RFC that I ignored for a while: don’t put stack traces in Implementing it in a Laravel app is about fifteen lines in the exception handler. In Go it’s a struct and a helper. There’s no framework work here, which is part of why the low adoption bugs me.<\/p>\n I shipped Here’s the version I used to write:<\/p>\n If three posts get inserted between the user’s request for page 1 and page 2, three posts that were on page 1 shift onto page 2. The user sees them twice. If posts get deleted instead, rows slide the other way and vanish entirely. And on a large table, The cursor version:<\/p>\n Two details that took me embarrassingly long to get right. First, you need a tiebreaker column. Sorting by Second, the token has to be opaque. Google’s AIP-158 on pagination<\/a> is blunt about this: page tokens must be opaque, URL-safe strings that users can’t deconstruct, because the moment someone can parse your token, your pagination internals are part of your public API and you can never change them. I base64 a small signed payload. I’ve also seen people encrypt it. Either beats handing out a raw timestamp and hoping.<\/p>\n AIP-158 also suggests expiring tokens after a few days rather than storing them forever, which I didn’t do and probably should.<\/p>\n The trade-off is real, so I’ll name it: cursors give up random page access. You can’t jump to page 47. If your UI has numbered page buttons, offset is the honest choice and you should accept the drift. For infinite scroll and API consumers, cursors win every time. This is the same kind of decision I went through when I wrote up GraphQL vs REST in 2026<\/a> \u2014 the answer depends on the client, not on which one reads better in a blog post.<\/p>\n A user double-clicks a submit button. Their phone drops to 3G mid-request and the client retries. Your queue worker times out at 30 seconds, the job is re-queued, and the charge goes through twice.<\/p>\n I’ve been on the wrong end of this. It’s a bad afternoon.<\/p>\n The fix is an The part people skip is {\"errors\": {\"email\": [\"is invalid\"]}}<\/code>. Auth failures came back as {\"message\": \"unauthorized\"}<\/code>. The payment service returned {\"error\": {\"code\": \"card_declined\", \"msg\": \"...\"}}<\/code>. And one endpoint, memorably, returned a 200 with {\"success\": false}<\/code>.<\/p>\ntype<\/code>, status<\/code>, title<\/code>, detail<\/code>, and instance<\/code>. You can add your own fields on top.<\/p>\nHTTP\/1.1 422 Unprocessable Content\nContent-Type: application\/json\n\n{\n "errors": {\n "email": ["is invalid"],\n "age": ["must be a number"]\n }\n}\n<\/code><\/pre>\nHTTP\/1.1 422 Unprocessable Content\nContent-Type: application\/problem+json\n\n{\n "type": "https:\/\/api.example.com\/problems\/validation-error",\n "title": "Your request is not valid.",\n "status": 422,\n "errors": [\n { "pointer": "#\/email", "detail": "must be a valid address" },\n { "pointer": "#\/age", "detail": "must be a positive integer" }\n ]\n}\n<\/code><\/pre>\ntype<\/code>. It’s a URI, it never changes, and clients switch on it instead of on the status code or on string-matching the message. The RFC is explicit that consumers should treat the type URI as the primary identifier and shouldn’t parse detail<\/code> for information. I’ve watched two separate teams break clients by rewording an error message, and both times the fix was this.<\/p>\ndetail<\/code>. Problem details describe the HTTP interface, not your internals. I once shipped an API where a Postgres constraint name leaked into the error body, which told anyone paying attention exactly what my schema looked like.<\/p>\nRule 2: offset pagination is a lie your database tells you<\/h2>\n
?page=2&per_page=50<\/code> for years. It’s fine right up until the data moves under you, and then it silently duplicates and skips rows, and nobody notices because nobody tests pagination against a table that’s being written to.<\/p>\n\/\/ Old: offset pagination\n$posts = Post::orderBy('created_at', 'desc')\n ->skip(($page - 1) * $perPage)\n ->take($perPage)\n ->get();\n<\/code><\/pre>\nOFFSET 100000<\/code> still makes Postgres walk 100,000 rows before discarding them.<\/p>\n\/\/ New: cursor pagination\n$query = Post::orderBy('created_at', 'desc')->orderBy('id', 'desc');\n\nif ($cursor = $request->query('page_token')) {\n [$ts, $id] = decode_cursor($cursor);\n $query->whereRaw('(created_at, id) < (?, ?)', [$ts, $id]);\n}\n\n$posts = $query->take($perPage + 1)->get();\n$hasMore = $posts->count() > $perPage;\n$posts = $posts->take($perPage);\n\nreturn [\n 'items' => $posts,\n 'next_page_token' => $hasMore ? encode_cursor($posts->last()) : null,\n];\n<\/code><\/pre>\ncreated_at<\/code> alone breaks the moment two rows share a timestamp, which happens constantly in seeded data and bulk imports. The (created_at, id)<\/code> row comparison handles it in one clause.<\/p>\nRule 3: idempotency keys on anything that moves money<\/h2>\n
Idempotency-Key<\/code> header: the client generates a UUID, sends it with the request, and the server remembers the response for that key. Same key twice, same response, one charge.<\/p>\n\/\/ Before: hope for the best\nfunc CreateCharge(w http.ResponseWriter, r *http.Request) {\n var req ChargeRequest\n json.NewDecoder(r.Body).Decode(&req)\n charge, err := billing.Charge(req.Amount, req.CustomerID)\n \/\/ ... a retry here creates a second charge\n}\n<\/code><\/pre>\n\/\/ After: record the key before doing the work\nfunc CreateCharge(w http.ResponseWriter, r *http.Request) {\n key := r.Header.Get("Idempotency-Key")\n if key == "" {\n problem.Write(w, 400, "missing-idempotency-key")\n return\n }\n\n if cached, found := store.Get(key); found {\n w.WriteHeader(cached.Status)\n w.Write(cached.Body)\n return\n }\n\n \/\/ INSERT ... ON CONFLICT DO NOTHING \u2014 the DB is the lock\n if !store.Claim(key, 24*time.Hour) {\n problem.Write(w, 409, "request-in-flight")\n return\n }\n\n charge, err := billing.Charge(req.Amount, req.CustomerID)\n store.Complete(key, 200, charge)\n \/\/ ...\n}\n<\/code><\/pre>\nClaim<\/code>. Checking a cache and then doing the work is a race: two concurrent retries both miss the cache, both charge. You need an atomic claim, and a unique index with ON CONFLICT DO NOTHING<\/code> is the cheapest one you already have.<\/p>\n