Should the new API be GraphQL?
A fitness company's planning meeting asks it, and it cannot be answered as asked. A phone app logs runs and opens on recent workouts, plan progress and friends' kudos. Coaches review their athletes on a web dashboard. A watch maker and an insurer read workouts through a partner integration. And a dozen internal services call each other, from workout storage to heart-rate analysis. Each caller wants something different from an API, so the style is chosen by who calls and what those calls need, not once for the company.
An API style is the shape of the conversation: what a request names, how the answer is shaped, and what contract the two sides share. Three are common, and each makes a different kind of call cheap.
Resources the web already understands
REST models the domain as resources with URLs, such as /athletes/81/workouts/2210, and applies HTTP's own methods to them: GET reads, PUT replaces what is at that URL, DELETE removes it, and POST hands the server data to process, most often to create a resource. Its strength is what HTTP gives it for free. A GET response can be stored by browsers, CDNs and proxies when its headers allow it; status codes such as 404, 409 and 429 mean the same thing to every client, monitor and retry library; and anyone can try an endpoint with curl. That suits the partners, who read new workouts on a schedule from code the company does not control, and expect a documented REST API with an OpenAPI description. Which headers make a response cacheable is HTTP caching: Cache-Control, ETags & revalidation.
Eight requests for one screen
The phone's home screen is where these REST endpoints, each returning one fixed shape, start to hurt. To draw it, the app fetches the three recent workouts, then each one's route summary, then the kudos on each, then the athlete's plan: eight requests, and most cannot start until the first answers, because they need its ids. HTTP/2 runs independent requests side by side on one connection, but not requests that wait on each other's answers (Network protocols: TCP, UDP, HTTP/2 & HTTP/3), so on a mobile network each dependent step costs another round trip. And each response carries every field its endpoint has, heart-rate samples included, for a screen that shows four. Those are under-fetching, several calls for one view, and over-fetching, more data than the view needs. An endpoint per screen, or parameters that select fields and embed relations, can fix both, but each is designed endpoint by endpoint on the server; a server-side layer per client that composes the calls is The BFF tier: gateway, sessions & fan-out.
One query in the shape of the screen
GraphQL turns this around. The server publishes a typed schema of everything a client may ask for, and the client sends one query naming the fields it wants, nested along the relations: recent workouts, each with distance, duration and a kudos count, plus the plan's name and this week's progress. One request, one response shaped like the screen, nothing the screen does not draw. The coaches' dashboard asks for other fields of the same types without a server change, and writes are mutations declared in the same schema.
That flexibility is paid for on the server, in three places.
First, the calls behind each query. Every field has a resolver, the function that fetches its value. Resolved naively, kudos on 50 workouts is one call for the list and then 50 calls to the kudos service, one per workout: the N+1 problem, moved from the client's network to the server's (N+1 queries: lazy loading, joins & batching covers it in general). The usual fix is batching inside the request, the DataLoader pattern: resolvers ask a loader for keys, the loader waits until the current round of resolvers has run, then sends one call for all 50.
Second, queries nobody meant to write. A client can nest relations as deep as the schema allows, athletes to followers to their workouts to their kudos, until one request asks for millions of rows. A REST endpoint's fixed shape caps that; a GraphQL server needs its own limits: a maximum depth, a cost computed for each query before it runs, a timeout. GitHub's public GraphQL API rate-limits by computed query cost, not by request count; limits in general are Rate limiting. For the company's own apps, tighter still is an allowlist of the queries they ship with, so the server runs nothing else.
Third, HTTP caching. Most GraphQL clients send every query as a POST to one URL, /graphql, and shared caches in practice do not store POST responses, so the edge caching REST had for free is gone. Persisted queries win some of it back: the client sends only the id or hash of a query the server already holds, with its variables, which fits in a GET URL that a shared cache can store when its cache key covers what makes the response differ; this personal home screen is sent private. The GraphQL over HTTP draft specification allows GET for queries, never for mutations.
Calls between services
Between services the trade changes. When the workouts service asks the plans service to recompute this week's progress, there is no browser and no partner, only a hot path called thousands of times a second, with both sides built by the same engineers. gRPC is designed for that. The contract is a .proto file of services and messages in Protocol Buffers, and a compiler generates client and server code in each language. In a statically typed language, code that still uses a field's old name or a wrong type fails to compile against the regenerated code. Versions already deployed still depend on the .proto's compatibility rules. Messages travel in a compact binary encoding, usually smaller and faster to parse than the same data as JSON. A call can carry a deadline, sent with the request (Timeout covers passing it on). And a call can stream: the heart-rate service takes a run's samples as a stream of messages instead of one huge request.
gRPC runs over HTTP/2, and browsers do not give page scripts the control over HTTP/2 that it needs, so a web page cannot call a gRPC service directly: it goes through an HTTP API in front of it, or through gRPC-Web, a variant translated by a proxy such as Envoy or spoken by a server that supports it, without client or bidirectional streaming. And since one connection carries many calls, a balancer that spreads connections rather than requests can pin all of a client's calls to one server (Service discovery & the mesh).
Three styles, one rule
Here that comes out as all three: GraphQL for the company's own apps, REST for partners, gRPC between services. A rule stated by caller is also one a reviewer can check; when each team picks a style per endpoint instead, clients can end up learning three conventions for one domain.
Both APIs stay thin: they turn a caller's request into gRPC calls to the services that hold the logic and the data.
Each of the three has its API contract, an OpenAPI description, a GraphQL schema, .proto files, and publishing it is what lets clients and servers agree, tooling generate code, and a change be checked before it ships. Without one, the two sides drift apart, and a client failing in production is the first anyone hears of it. Changing a contract without breaking its callers is API versioning & backwards compatibility; the front door that authenticates and routes all this traffic is API gateway & the edge.
Practice: a style for each caller
Among the parts the URL Shortener Challenge offers is a GraphQL API, and the question to settle on your Grid is whether it earns a place on the redirect path. A redirect is a keyed GET, read about 100 times for every link created, with one value in the answer, the target in a Location header, and nothing for a client to shape, which is the case where plain HTTP and a cache already fit and a GraphQL layer adds a hop and a resolver with no benefit. Distributed Lock Service poses the question from the other side: all its callers are services, and acquire, release and watch are small, latency-critical calls, one of which wants to stream changes back. Is gRPC the surface they need?