GraphQL: Ask for Exactly What You Need

Sooner or later Vera will open a partner's documentation and find something missing: no list of addresses. No stations endpoint, no rides endpoint, no table of paths at all. Just one address, and beneath it a block of text in curly brackets that looks like JSON with all the values removed. Nothing is broken and nothing is beyond her. This is GraphQL, the most common style of API that is not the one this book taught, and one page of recognition is exactly the right dose.

GraphQL is a query language for APIs. Instead of many addresses that each return a fixed shape, there is one address, and you send it a query: a written description of precisely which fields you want back. Picture a restaurant with a fixed menu next to a deli counter with an order slip. The menu brings you set plates, each with everything the kitchen decided goes on it; at the counter you tick the items you actually want and get exactly those, on one plate. Both feed you. The slip takes a little learning to fill in.

One Address, and You Bring the Question

The address is usually spelled /graphql, and requests to it are almost always POSTs: the query travels in the body, which is what Chapter 3 taught a body is for. What comes back is JSON, read exactly the way Chapter 4 taught you to read it. The one genuinely new thing is the query itself, and its rule is simple enough to state in a sentence: you write out the fields you want, nested the way you want them, and the server fills in the values.

{ station(id: "st_014") { name free_bikes } }

{"data": {"station": {"name": "Old Market", "free_bikes": 9}}}

Read that pair and the whole idea lands. The request named a station and asked for two things about it. The answer holds those two things, in that order, and not the capacity, the status or the coordinates that Chapter 4's station object also carries. The response is the question with the blanks filled in — which is why a GraphQL answer never surprises you with its shape.

Because there is no menu of addresses to browse, the provider publishes a schema instead: the full list of things you can ask for and which fields each one has. That schema is the documentation, and it is machine-readable, which is why the GraphQL world lives inside interactive query explorers — the same idea as the Swagger UI page from Chapter 6, wearing different clothes.

The Problem It Was Built For

Two everyday annoyances motivated GraphQL, and both have plain names. Over-fetching is getting far more than you asked for: a phone app needs a station's name, and the endpoint sends the name, capacity, free bikes, status and coordinates, over a mobile connection, for all 214 stations. Under-fetching is the opposite: what you need lives in three different places, so one screen costs three round trips before it can draw anything.

GraphQL was built at the scale where those two costs stop being tidiness and start being money and battery life. One request, precisely shaped, replaces three fat ones. If a provider you meet has chosen GraphQL, this is almost always why — worth knowing, because "why did they build it that way?" is a question that comes up in meetings and has a real answer.

What It Costs

Nothing is free. First, there is a query language to learn, and it is a real one: nesting, arguments, variables, fragments. Reading a simple query takes ten minutes; writing good ones takes a while longer.

Second, the tooling matters more than it does here. You can send a GraphQL query with curl — it is a POST with a body, after all — but it is grim work, because the query has to be squeezed into a JSON string with quotes escaped. In practice everyone uses the explorer that ships with the docs, which knows the schema and completes field names as you type.

Third, some instincts from Chapter 8 get subtler. Caching is easier when the same address always means the same answer; at a GraphQL counter every request is a POST to one address with a unique body, so the simple caching of Chapter 8 does not apply and providers reach for other mechanisms. Rate limits get re-thought too, since "60 requests a minute" means little when one request can ask for a hundred times more work than another.

Spotting One, and What Still Applies

The recognition kit is short. One endpoint named /graphql, requests sent as POST regardless of whether they read or write, documentation built around an interactive explorer rather than a list of paths, and the word "schema" doing the work "endpoint reference" does here. Any two of those and you know what you are looking at.

What transfers is more than you would guess. GraphQL rides on ordinary HTTP: the same headers, the same Authorization key from Chapter 5, the same TLS padlock, the same 401 when the key is missing. One instinct does need adjusting, and it is worth knowing before it confuses you: a GraphQL server often answers 200 even when your query was wrong, and describes the trouble in an errors field inside the body. The habit from Chapter 7 still holds — read the body, it names the reason — but the status line alone is a weaker signal here than it was at Tandem's counter.