REST vs GraphQL vs gRPC: Choosing an API Style

Three doors to the same room

Every API does the same job: a client asks for data or an action, a server answers. REST, GraphQL, and gRPC are three different contracts for that conversation. They are not ranked, there is no 'best' one. They are tuned for different callers, different networks, and different teams. Pick by the shape of your problem, not by what trended last quarter.

REST gives you a menu of resources. GraphQL gives you a kitchen and a language to order from it. gRPC gives you a private phone line to a specific colleague who already knows your shorthand.

An analogy: three ways to order lunch

Before any code, anchor the three styles to something physical. The difference between them is really a difference in *who shapes the request* and *how tightly the two sides agreed in advance*.

The picture: one client, three back-ends

In a real system you rarely choose only one. A typical setup puts a gateway in front: the browser or mobile app talks one friendly protocol to the edge, and the gateway fans out to whichever style each downstream service speaks.

1. 1

   Client makes one request

   The app sends a single HTTPS call to the gateway, it never needs to know how many services live behind it.

2. 2

   Gateway authenticates and routes

   It validates the token once, then decides which downstream service (and which protocol) serves this path.

3. 3

   Fan-out to the right style

   Cacheable catalog reads go to a REST service; a screen needing many joined fields hits the GraphQL server; latency-sensitive internal calls use gRPC.

4. 4

   Compose and return

   The gateway stitches the responses into one payload shaped for the client and sends it back.

This is the key mental shift: the three styles are not competitors fighting for your whole system. They are tools for different *edges* of it. See API gateways and the edge for how this front door is built.

The big comparison

Here is the whole debate on one screen. Read each row as 'what does this style optimise for, and what does it cost me?'

Same request, three dialects

Nothing makes the difference concrete like one task in all three styles. The task: get a user with their orders. Watch how the request shape and the contract change.

REST: two resources, fixed shapes

GET /users/42 HTTP/1.1
Host: api.shop.com
Accept: application/json

# Response: the full user resource (every field, fetched or not)
{
  "id": 42,
  "name": "Ada",
  "email": "ada@shop.com",
  "createdAt": "2026-01-04T10:00:00Z"
}

# Orders are a separate resource, a second round trip
GET /users/42/orders HTTP/1.1

REST is dead simple to read, cache, and debug, but you get the *whole* user even if you wanted only the name, and you pay two round trips. That is over-fetching (too many fields) and under-fetching (too few resources per call) in one example.

GraphQL: one call, exactly the shape you asked for

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

# Response mirrors the query exactly, no extra fields, one round trip
{
  "data": {
    "user": {
      "name": "Ada",
      "orders": [
        { "id": "o_91", "total": 49.0 },
        { "id": "o_88", "total": 12.5 }
      ]
    }
  }
}

One request, only the fields the screen needs, joined across user and orders. Over- and under-fetching solved. The cost shows up elsewhere, see the N+1 warning below.

gRPC: a typed contract compiled into both sides

syntax = "proto3";
package shop.v1;

service UserService {
  rpc GetUserWithOrders(GetUserRequest) returns (UserWithOrders);
}

message GetUserRequest {
  int64 user_id = 1;
  int32 last_orders = 2;
}

message Order {
  string id = 1;
  double total = 2;
}

message UserWithOrders {
  int64 id = 1;
  string name = 2;
  repeated Order orders = 3;
}

You define the contract once in a .proto file, then generate type-safe clients and servers in every language. Calls travel as compact binary over a reused HTTP/2 connection, fast and strict, but opaque to a casual curl and awkward from a browser. For how a contract like this evolves without breaking callers, see API design, evolution, and versioning.

The two sharpest gotchas

Each of the newer styles has one trap that bites teams hard in production. Know them before you commit.

import DataLoader from "dataloader";

// Batches every orders-by-userId lookup in one tick into ONE query
const orderLoader = new DataLoader(async (userIds: readonly number[]) => {
  const rows = await db.orders.findByUserIds(userIds);
  // Return results in the SAME order as userIds (DataLoader's contract)
  return userIds.map((id) => rows.filter((r) => r.userId === id));
});

const resolvers = {
  User: {
    orders: (user: { id: number }) => orderLoader.load(user.id),
  },
};

How to choose

Skip the religion. Walk down this list and stop at the first match, it is right far more often than agonising over benchmarks.

1. Public API for third parties, or heavy cacheable reads? Reach for REST. Everyone knows it, every tool speaks it, and HTTP caching is free money.
2. One client (web/mobile) pulling many fields from many sources per screen? Reach for GraphQL, usually as a BFF (backend-for-frontend). It kills over- and under-fetching and lets the front end evolve without new endpoints.
3. Internal service-to-service calls where latency and strict typing matter? Reach for gRPC. Compact binary, HTTP/2 multiplexing, generated clients, and real streaming.
4. Need real-time bidirectional streams (chat, telemetry, live updates) between services? gRPC streaming is purpose-built; GraphQL subscriptions or SSE are the browser-facing alternatives.
5. Small team, simple CRUD, ship today? REST. Do not add a query language or a protobuf toolchain to a problem that a dozen endpoints solve.

Common mistakes that cost hours

1. Picking GraphQL to look modern, then re-implementing caching and rate-limiting by hand. You gave up free HTTP caching; make sure the flexibility was worth it.
2. Ignoring the N+1 problem until the DB melts under load. Add DataLoaders from day one in any resolver that fans out to children.
3. Exposing gRPC to browsers without grpc-web and a proxy, then wondering why nothing connects. Use REST or GraphQL at the browser edge; keep gRPC internal.
4. Treating REST as 'no schema needed'. Untyped JSON drifts. Write an OpenAPI spec so clients and tests have a contract, see REST API design.
5. Letting a GraphQL query depth or cost go unbounded. A single nested query can become a denial-of-service. Add depth limits and query cost analysis.
6. Versioning a gRPC contract by editing field numbers. Field tags are forever, only add new ones; never renumber or reuse, or you silently corrupt old clients.

Takeaways

Where to go next

You now have a decision framework. Deepen each branch with these, then practise designing a contract end to end:

• REST API design, resources, status codes, and how to keep a REST surface clean.
• API design, evolution, and versioning, changing any contract without breaking callers.
• API gateways and the edge, the front door that lets REST, GraphQL, and gRPC coexist.
• Practise in the networking lab to build intuition for HTTP/1.1 vs HTTP/2 under the hood.