REST vs RPC (gRPC) vs GraphQL

An API is the menu a service offers to its callers. There are three common ways to write that menu.

REST: things and verbs

REST treats everything as a resource with a URL, and uses HTTP methods as the verbs:

GET    /users/42            read user 42
GET    /users/42/orders     read their orders
POST   /users/42/orders     create an order
DELETE /orders/7            delete order 7

It's simple, works with any HTTP client, and plays well with HTTP caching. The catch is that the server decides the shape of each response. A screen that needs bits of several resources may need several calls (under-fetching), or get much more data than it needs (over-fetching).

RPC: call a function

RPC (remote procedure call) makes a network call look like calling a function: getUser(42), placeOrder(cart). gRPC is the popular modern version:

• You define the functions and messages in a schema file (Protocol Buffers).
• Messages are sent in a compact binary format over HTTP/2: smaller and faster than JSON.
• Code for clients and servers is generated from the schema, in many languages.
• It supports streaming in both directions.

It's a favourite between services inside a company, where speed matters and both sides share the schema. It's less handy for browsers, which can't speak it directly without a proxy.

GraphQL: ask for exactly what you need

GraphQL gives clients one endpoint and a query language. The client describes the shape it wants:

{ user(id: 42) { name  orders(last: 3) { total } } }

and gets exactly that, in one round trip. Great for apps with many different screens, especially mobile on slow networks. The costs: the server is more complex, one innocent-looking query can ask for a huge amount of work (so you need limits), and plain HTTP caching works less well because everything goes through one URL.

Choosing

Many companies use all three: REST or GraphQL at the edge, gRPC inside.

Key idea: REST is resources plus HTTP verbs; simple and cache-friendly. gRPC is fast, typed function calls, best between services. GraphQL lets the client ask for exactly the data it needs, at the cost of server complexity.