REST, GraphQL and gRPC

REST, GraphQL and gRPC are not competing versions of one thing. They make different trade-offs, and an interviewer asking "which would you use?" wants to hear the trade-offs, not a favourite.

REST

Resources identified by URIs, manipulated with HTTP methods, with status codes, caching, conditional requests and content negotiation all coming from HTTP itself — the subject of this whole course. It works with every client, every proxy and every CDN, and is easy to explore with nothing but curl.

Its weak spot is fixed response shapes. A screen that needs a user's name and the titles of their last three orders either receives far more than it needs (over-fetching) or makes several requests to assemble it (under-fetching), each one a round trip on a mobile network.

GraphQL

A typed schema plus a query language: the client says exactly which fields it wants, nested as deep as the schema allows, and gets that shape back in one response.

query {
  user(id: "7") {
    name
    orders(last: 3) { title }
  }
}

1const users = { 7: { id: "7", name: "Nino", email: "nino@example.com", address: "Tbilisi", plan: "pro" } };2const orders = {3  7: [4    { id: "o1", title: "Desk lamp", total: 4200, items: 1, status: "delivered" },5    { id: "o2", title: "Notebook", total: 900, items: 3, status: "shipped" },6  ],7};8 9// REST: fixed shapes, one request per resource.10function restScreen(id) {11  const calls = [];12  const get = (path, body) => { calls.push(path); return body; };13  const user = get(`/users/${id}`, users[id]);14  const list = get(`/users/${id}/orders`, orders[id]);15  const bytes = JSON.stringify(user).length + JSON.stringify(list).length;16  return { requests: calls.length, bytes, name: user.name, titles: list.map((o) => o.title) };17}18 19// GraphQL-style: the client names the fields, one response.20function graphScreen(id) {21  const body = { user: { name: users[id].name, orders: orders[id].map((o) => ({ title: o.title })) } };22  return { requests: 1, bytes: JSON.stringify(body).length, name: body.user.name, titles: body.user.orders.map((o) => o.title) };23}24 25export function run() {26  return { rest: restScreen(7), graphql: graphScreen(7) };27}

What it costs:

• HTTP caching mostly goes away. Queries are usually POSTed to a single endpoint, so CDNs and browser caches see one URL; caching moves into client libraries and the server.
• Errors live in the body. A GraphQL response has data and errors, and can be a partial success — some fields resolved, others null with an error. Many servers answer such responses with HTTP 200, so monitoring must read the body, not the status code.
• Clients can write expensive queries. A deeply nested query can fan out into thousands of database calls; servers need depth or complexity limits, and batching in resolvers to avoid the N+1 query problem.
• It evolves by adding fields and marking old ones @deprecated, rather than by versioning — which works because clients only receive the fields they asked for.

GraphQL shines when many different clients (web, iOS, Android, partners) need different slices of a rich, connected domain.

gRPC

An RPC framework: services and messages are defined in Protocol Buffers (.proto files), client and server code is generated for many languages, and calls travel as compact binary messages over HTTP/2.

service Orders {
  rpc GetOrder (GetOrderRequest) returns (Order);
  rpc WatchOrders (WatchRequest) returns (stream OrderEvent);
}

It supports unary calls and server, client and bidirectional streaming, has deadlines built in, and uses its own status codes (NOT_FOUND, UNAVAILABLE, DEADLINE_EXCEEDED, …) instead of HTTP ones. Compatibility rules are strict and simple: add fields with new numbers, never reuse or renumber an existing field.