APIs: REST, GraphQL, gRPC

REST: Constraints, Not a Standard

REST is not a protocol or a specification. It is an architectural style described by Roy Fielding in his 2000 dissertation. A REST API is one that satisfies six constraints: client-server separation, statelessness, cacheability, uniform interface, layered system, and optional code on demand. Most APIs called "RESTful" satisfy only the first three and ignore the rest, particularly HATEOAS (Hypermedia As The Engine Of Application State).

In practice, REST means resources identified by URLs, manipulated via HTTP verbs, with representations in JSON (or XML). The protocol does the heavy lifting: caching via ETags and Cache-Control, content negotiation via Accept headers, authentication via Authorization headers. The tradeoff is that the client drives everything. The server cannot push updates; the client must poll.

HTTP verbs and their contracts

Safe means the operation has no side effects.Idempotent means calling it N times produces the same result as calling it once. Safe implies idempotent. POST is neither. PUT and DELETE are idempotent but not safe.

Status codes worth knowing

URL design principles

/getUser?id=42
/api/createPost
/users/getFollowers
/deleteComment/5
/api/v1/user_list

GET /users/42
POST /posts
GET /users/42/followers
DELETE /comments/5
GET /users

API versioning strategies

The over-fetching problem

REST couples resource shape to endpoint. A GET /users/42 returns the entire user object whether the client needs one field or all of them. A mobile app showing a user avatar and name burns bandwidth downloading the full profile. Worse, a page that needs user, post, and comment data must make three sequential requests before it can render.

Partial solutions exist: sparse fieldsets (?fields=id,name), compound documents (embed related resources in the response), and purpose-built endpoints (/api/post-card-data). All of these are workarounds. They either push the problem to the client (sparse fieldsets), over-engineer the API (compound documents), or erode the uniform interface (bespoke endpoints). GraphQL emerged specifically to solve this.

GraphQL: Query What You Need

GraphQL was developed at Facebook in 2012 and open-sourced in 2015. The motivation was direct: the News Feed required data from dozens of different backend services, and REST endpoints could not express the variable, nested, client-driven shape of that data efficiently. GraphQL moves the query language to the client side.

At the center is the schema. The server defines a type system: every object type, every field, every relationship between types. Clients write queries in the GraphQL query language that traverse this type graph. The server validates queries against the schema at parse time and returns exactly the fields requested, nothing more, nothing less.

GET /api/v1/posts/42

  -> also needed:

GET /api/v1/users/1
GET /api/v1/posts/42/comments?count=true

Three round trips before the
page can render.

{
  "id": 42,
  "title": "Building at Scale",  ✓ needed
  "excerpt": "A deep dive...",   ✓ needed
  "content": "Lorem ipsum...",   ✗ 5 KB, not needed
  "slug": "building-at-scale",   ✗ not needed
  "author_id": 1,                ✗ need name, not id
  "created_at": "2025-01-01T...",✗ not needed
  "updated_at": "2025-01-15T...",✗ not needed
  "view_count": 14200,           ✗ not needed
  "status": "published",         ✗ not needed
  "category_id": 3               ✗ not needed
}
  + separate responses for
    /users/1 and /comments count

Three operation types

query { user(id: 42) { name email } }

mutation { createPost(title: "Hello") { id } }

subscription { newComment(postId: 42) { text author { name } } }

Schema design: a minimal example

type Query {
  post(id: ID!): Post
  posts(first: Int = 20, after: String): PostConnection
  user(id: ID!): User
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
  deletePost(id: ID!): Boolean!
}

type Post {
  id: ID!
  title: String!
  excerpt: String
  commentCount: Int!
  author: User!          # resolved separately, DataLoader target
  tags: [Tag!]!
  createdAt: DateTime!
}

type User {
  id: ID!
  name: String!
  avatarUrl: String
}

type Tag { name: String! }

input CreatePostInput {
  title: String!
  excerpt: String
}

# Relay-style cursor pagination
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}
type PostEdge { node: Post!; cursor: String! }
type PageInfo { hasNextPage: Boolean!; endCursor: String }

The DataLoader pattern

The most common GraphQL performance bug is the N+1 problem. When you resolve a list of 100 posts and each post resolver independently fetches its author, you execute 101 queries. DataLoader solves this by collecting all keys within a single event loop tick and issuing a single batched query.

// posts resolver
posts.forEach(post => {
  // N separate queries
  db.query(
    "SELECT * FROM users WHERE id = ?",
    [post.authorId]
  );
});
// 100 posts = 101 queries

const userLoader = new DataLoader(
  async (ids) => {
    const users = await db.query(
      "SELECT * FROM users WHERE id = ANY(?)",
      [ids]
    );
    return ids.map(id =>
      users.find(u => u.id === id)
    );
  }
);
// 100 posts = 2 queries total

Benefits and costs

gRPC: Protocol Buffers and HTTP/2

gRPC is a remote procedure call framework developed at Google and open-sourced in 2015. It uses Protocol Buffers as its interface definition language and serialization format, and HTTP/2 as its transport. The combination gives it properties that REST and GraphQL cannot match: strongly typed schemas enforced at compile time, binary serialization 3-10x smaller than JSON, multiplexed streams over a single TCP connection, and server push.

The workflow is schema-first and code-generated. You define your service in a .proto file. The gRPC compiler (protoc) generates type-safe client stubs and server interfaces in your language of choice. The generated code handles serialization, deserialization, and transport. You implement the server interface and call the client stub as if it were a local function.

Protocol Buffers: how binary encoding works

Protocol Buffers (protobuf) encode messages as binary sequences of field-number/value pairs. Field names are not transmitted on the wire; only the field number is. This is what makes the format compact and why it is schema-dependent: you cannot decode a protobuf message without the .proto definition.

message User {
  int64  id         = 1;
  string name       = 2;
  string email      = 3;
  bool   is_active  = 4;
}

// Populated with:
// id: 42, name: "Alice",
// email: "a@ex.com", is_active: true

08 2A              field 1, varint, 42
12 05 41 6C 69     field 2, "Alice"
   63 65
1A 07 61 40 65     field 3, "a@ex.com"
   78 2E 63 6F
   6D
20 01              field 4, bool true

vs JSON (67 bytes):
{"id":42,"name":"Alice",
"email":"a@ex.com",
"is_active":true}

Field names absent on the wire. Unknown field numbers are silently skipped (forward compatibility). Missing fields use the type default (0, "", false). This is how .proto achieves backward and forward compatibility without versioning.

Scalar types and wire sizes

HTTP/2 and multiplexing

REST over HTTP/1.1 opens one TCP connection per in-flight request (or reuses connections serially). HTTP/2 sends multiple streams over a single connection simultaneously using framing. Each request/response pair is a stream. Streams are independent: a slow response does not block a fast one (head-of-line blocking is eliminated at the HTTP layer).

Four streaming modes

rpc GetUser(UserRequest) returns (User);

rpc WatchLogs(LogQuery) returns (stream LogEntry);

rpc UploadChunks(stream Chunk) returns (UploadResult);

rpc Chat(stream Message) returns (stream Message);

When NOT to use gRPC

Choosing the Right Paradigm

REST, GraphQL, and gRPC are not competing alternatives where one wins. They are tools with different strengths that often coexist in the same system. The right choice depends on your client type, latency requirements, team experience, and schema complexity. No architecture uses a single paradigm end-to-end at scale.

Decision matrix

Hybrid architectures

Production systems rarely use one paradigm throughout. The most common hybrid patterns combine paradigms to get the best properties of each at the right layer of the stack.

Public: POST /orders  |  Internal: OrderService.CreateOrder (gRPC)

Browser -> GraphQL BFF -> [UserService, PostService, CommentService] (gRPC)

POST /payments (REST) + query { paymentHistory { ... } } (GraphQL)

Rules of thumb