API Design

What we're doing: Model an order resource and its lifecycle using nouns, HTTP verbs and correct status codes instead of verb-shaped endpoints.

POST /orders HTTP/1.1
Content-Type: application/json

{ "customerId": "cus_8891", "items": [{"sku": "A1", "qty": 2}] }

HTTP/1.1 201 Created
Location: /orders/42
Content-Type: application/json

{ "id": 42, "status": "pending", "customerId": "cus_8891" }

GET /orders/42 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "status": "pending", "customerId": "cus_8891" }

GET /orders/9999 HTTP/1.1

HTTP/1.1 404 Not Found
Content-Type: application/json

{ "error": "order_not_found", "message": "No order with id 9999" }

1

POST /orders creates a new order — the verb lives in the method, not in the path.

6

201 Created plus a Location header tells the client exactly where the new resource now lives.

19

404 reports a client-facing fact (this id does not exist) as a status code the client can branch on, rather than a message buried in a 200 body.

Why this works: Every response here carries its outcome in the status code first — a client can decide what to do (use the body, fix the request, retry) by checking one number before it even parses JSON.

What we're doing: Combine filtering, sorting and pagination in one collection request and read what each parameter does.

GET /orders?status=shipped&sort=-createdAt&limit=2 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 91, "status": "shipped", "createdAt": "2026-08-24" },
    { "id": 88, "status": "shipped", "createdAt": "2026-08-20" }
  ],
  "nextCursor": "eyJpZCI6ODh9"
}

1

status=shipped filters to an exact match; sort=-createdAt orders newest first; limit=2 caps the page size.

8

Only 2 of potentially thousands of shipped orders come back — the server did the filtering and sorting, not the client.

10

nextCursor is the token the client sends back to get the next page, covered in depth in cursor-vs-offset pagination.

Why this works: Each query parameter answers one independent question (which rows, what order, how many) and the server applies all three before the response is built — pushing that work to the client would mean downloading every row only to discard most of them.

What we're doing: Ship a breaking field rename without breaking clients still on v1.

GET /v1/orders/42 HTTP/1.1

HTTP/1.1 200 OK
{ "orderId": 42, "total": 59.99 }

GET /v2/orders/42 HTTP/1.1

HTTP/1.1 200 OK
{ "orderId": 42, "totalAmount": 59.99 }

# v1 is marked deprecated (Deprecation and Sunset
# headers) but keeps returning "total" unchanged
# until its announced retirement date.

1

Existing clients keep calling /v1 and keep getting the field name they were built against.

6

New clients (or v1 clients that have migrated) call /v2 and get the renamed field.

11

Both versions run simultaneously during the deprecation window — nobody is forced to migrate the instant v2 ships.

Why this works: Running both versions side by side turns a breaking change into a scheduled migration instead of an outage — every existing caller keeps working exactly as before until it chooses to move, or until the announced sunset date arrives.

What we're doing: Show offset pagination skipping a row when a delete happens between two page requests, and cursor pagination staying correct under the same delete.

Starting rows, ordered by id: [1, 2, 3, 4, 5, 6]

-- OFFSET PAGINATION, page size 2 --
Request 1: GET /orders?limit=2&offset=0  -> [1, 2]
   (meanwhile, row 2 is deleted)
Request 2: GET /orders?limit=2&offset=2  -> [4, 5]
   Row 3 was never returned: after the delete, row 3
   shifted into offset-2's old position and was
   skipped when the server skipped "2 rows" again.

-- CURSOR PAGINATION, page size 2 --
Request 1: GET /orders?limit=2               -> [1, 2], nextCursor=2
   (meanwhile, row 2 is deleted)
Request 2: GET /orders?limit=2&cursor=2      -> [3, 4]
   Row 3 IS returned: the cursor means "rows with
   id > 2", which is unaffected by row 2 being
   deleted -- it was never a position count.

5

Offset 0 returns rows 1 and 2 -- normal first page.

7

The delete of row 2 shifts every later row one position to the left.

8

Offset 2 now skips rows 1 and 3 (the new "first two"), not rows 1 and 2 as the client assumed -- row 3 is silently lost.

15

Cursor=2 means "id greater than 2", a condition unaffected by row 2 itself being deleted.

Why this works: Offset counts positions, and positions shift when rows are inserted or deleted ahead of the current page. A cursor encodes a value (here, an id), and a WHERE id > cursor condition stays correct regardless of how many rows before that value come or go.

What we're doing: Contrast a mutable natural key used as an identifier against a stable surrogate key, and show the resulting error contract when a lookup fails.

# BAD: email used as the identifier
GET /users/alice@example.com HTTP/1.1
# Breaks the moment Alice changes her email --
# every bookmark, webhook and stored reference
# using the old address now 404s.

# GOOD: stable surrogate id, email is just a field
GET /users/usr_9f83a1 HTTP/1.1

HTTP/1.1 200 OK
{ "id": "usr_9f83a1", "email": "alice@example.com" }

# error contract on a failed lookup
GET /users/usr_00000 HTTP/1.1

HTTP/1.1 404 Not Found
{
  "error": {
    "code": "user_not_found",
    "message": "No user with id usr_00000",
    "requestId": "req_8f3a2b1c"
  }
}

2

The URL itself encodes a field (email) that the user is allowed to change — any change breaks this URL for everyone already holding it.

8

usr_9f83a1 never changes even if every other field on the user record does, including email.

20

The error contract's code field lets client code branch on user_not_found without parsing the message string.

Why this works: An identifier and an error response are both contracts other systems depend on — changing either one's shape without warning breaks every caller that already parsed the old shape, which is exactly the failure stable identifiers and explicit error contracts exist to prevent.