API styles

GraphQL: ask for exactly the fields you want

A REST endpoint is a set menu: you get what's on the plate. That causes two problems. A phone screen showing only campaign names still receives every field, which is over-fetching. And a page needing a customer and their orders has to make two or three calls, which is under-fetching.

GraphQL, from Facebook, is ordering exactly what you want. There's one endpoint. The client sends a query describing the shape it wants, and gets back exactly that:

query {
  customer(id: "c_42") {
    name
    orders(last: 3) { id total }
  }
}

The answer is JSON with the same nesting: a name, and three orders with two fields each.

In plain words: with REST, the server decides what comes back. With GraphQL, the client does.

The cost moves to the kitchen. One query can ask for a huge amount of data, so servers must limit how deep and how expensive a query can be. Caching is also harder, because every request is a POST to the same URL.

import json

products = [{"id": n, "name": f"Tent {n}", "price": 89.0, "stock": 14,
             "description": "A roomy two-person tent. " * 10,
             "reviews": list(range(20))} for n in range(20)]

rest = json.dumps(products)
graphql = json.dumps([{"name": p["name"], "price": p["price"]} for p in products])

print("REST bytes:", len(rest))
print("GraphQL bytes:", len(graphql))
print("REST is", round(len(rest) / len(graphql)), "times bigger")

import json

rest = ("GET", "/v1/campaigns/cmp_103", None)

json_rpc = ("POST", "/rpc", {
    "jsonrpc": "2.0", "id": 1,
    "method": "get_campaign",
    "params": {"id": "cmp_103"},
})

graphql = ("POST", "/graphql", {
    "query": 'query { campaign(id: "cmp_103") { name spend } }',
})

for name, (method, path, body) in [("REST", rest), ("JSON-RPC", json_rpc), ("GraphQL", graphql)]:
    print(f"{name:9} {method:4} {path:22} {json.dumps(body) if body else ''}")

Live updates: four ways to hear about changes

Say you're waiting for a parcel. You could phone the company every hour. They could text you when it ships. You could watch their live tracking page. Or you could stay on a call with the driver. Those are the four ways an app can hear about changes:

• Polling is phoning every hour. It's simple, and most calls are wasted.
• Webhooks are the text message. The provider contacts you, at a web address you gave it.
• Server-sent events are the tracking page: one long reply that keeps adding news, in one direction only.
• WebSockets are the phone call. Either side can speak at any time.

The Claude API streams tokens with SSE. Each event is a few lines like event: content_block_delta then data: {...}, separated by blank lines. That's why streaming works through ordinary HTTP libraries and proxies: to them, it's a normal response that takes a while to finish.

Picking a style, and what it costs

GET must not change anything. Browsers, caches and crawlers all feel free to repeat a GET, and to send one on their own. A "delete" link built on GET can be triggered by a link-preview bot. Anything that changes data needs POST, PUT, PATCH or DELETE.

REST means more than JSON over HTTP. An API with one URL, /api, that takes {"action": "delete_user"} is RPC, whatever its docs call it. That's not automatically wrong, and RPC is a good fit for actions that don't map onto resources. But knowing which one you have sets the right expectations, particularly for caching and retries.

GraphQL moves the cost, rather than removing it. Clients get exactly the fields they want. In exchange, your server has to protect itself from expensive queries, and URL-based caching stops working, since everything is a POST to one address. It pays off when many different clients need different shapes of data. For one web app talking to its own backend, plain REST is often simpler.

Polling is wasteful when the provider can tell you. Asking every second means 86,400 requests a day, and nearly all of them say "nothing new". If webhooks are available, use them. Keep a slow poll as a backup for missed events, since webhooks can fail too.

Choose one

Pick one style for your API, and use it throughout. People learn an API by guessing from the last endpoint they used, and every exception breaks that guess.