Designing a REST API

Status codes, precisely

Think of the status code as a stamp on a returned letter. The first digit says whose problem it is:

• 2xx: it worked.
• 4xx: the client must change something. Sending the same thing again won't help.
• 5xx: the server failed, and a retry might work.

These codes cover nearly every case:

For a request that is valid JSON but whose values break the rules, such as a negative budget, 422 Unprocessable Content fits best, though some APIs use 400 for all input errors. Never answer 200 with {"error": ...} inside. Clients, monitoring and retry logic all read the status code first, so they'd count the failure as a success.

One error shape, everywhere

If every department of a company sent complaints on a different form, nobody could process them. So pick one error format and use it for every endpoint. Here's Anthropic's:

{"type": "error", "error": {"type": "not_found_error", "message": "model: claude-opus-9 not found"}}

A machine-readable type lets code branch on it, and a human message says what to fix. Many APIs add a param naming the bad field. There's also an internet standard, problem details (RFC 9457), with type, title, status and detail fields. Which one you choose matters less than using it everywhere.

Filtering, sorting and pagination

Lists need options, passed as query parameters: GET /orders?status=paid&sort=-created&limit=20. A leading - for descending order is a common convention.

Never return an unbounded list. One day that list has a million rows. Pagination returns a page at a time, and there are two main ways.

Offset pagination (?offset=40&limit=20) means "skip 40, then give me 20". It's like saying "start at line 40". That's simple, but it breaks when data changes between pages. If a new order arrives while you read, every line shifts down by one, and one order appears on two pages:

orders = [f"order {n}" for n in range(10, 0, -1)]      # newest first
page1 = orders[0:4]
orders.insert(0, "order 11")                            # a new order arrives
page2 = orders[4:8]
print("page 1:", page1)
print("page 2:", page2)                                 # "order 7" appears twice

Large offsets are also slow, because the database still counts past every skipped row.

Cursor pagination is a bookmark. A bookmark marks where you stopped, however many pages get added before it. Each page of results ends with a next_cursor: a token that says where you stopped, such as the sort key of the last item. The next request asks for items after that point. New items can't shift anything, and the database can jump straight there with an index. The response looks like this:

{"data": [ ... ], "has_more": true, "next_cursor": "eyJhZnRlciI6IFsxNzMwLCAib3JkXzkiXX0"}

Make the cursor opaque: encode it, so clients pass it back without building or editing it. Then you're free to change what's inside.

import base64, json

def encode_cursor(position):
    raw = json.dumps({"after": position}).encode()
    return base64.urlsafe_b64encode(raw).decode().rstrip("=")

def decode_cursor(cursor):
    padded = cursor + "=" * (-len(cursor) % 4)          # put back the padding we removed
    return json.loads(base64.urlsafe_b64decode(padded))["after"]

c = encode_cursor([1730, "ord_9"])
print(c)
print(decode_cursor(c))

Versioning

Adding a dish to a menu upsets nobody. Taking away someone's usual order does. APIs work the same way.

Some changes are additive: a new endpoint, a new optional field, a new field in responses. Well-behaved clients ignore fields they don't know, so additive changes don't break anyone. Removing or renaming a field, changing a type or tightening a rule is breaking.

Breaking changes need a new version. There are two common styles:

• A version in the URL: /v1/campaigns, /v2/campaigns. It's easy to see and to route.
• A version in a header, often a date: the Claude API's anthropic-version: 2026-10-21. Each client keeps the behavior of the date it pinned, until it opts into a newer one.

Either way, keep old versions running long enough for clients to move, and announce removals well in advance.