API Design: REST, GraphQL & gRPC

The Three Major API Paradigms

Modern distributed systems communicate primarily through APIs. Three paradigms dominate: REST (the web's default), GraphQL (flexible client-driven queries), and gRPC (high-performance binary RPC). Each reflects different trade-offs between simplicity, flexibility, and performance.

REST: Representational State Transfer

REST is an architectural style built on HTTP conventions. Resources are identified by URLs, and HTTP verbs (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) represent operations. A well-designed REST API is self-describing, cacheable, and stateless.

# Create a user
POST /users
Content-Type: application/json
{"name": "Alice", "email": "alice@example.com"}

# Read a user
GET /users/123

# Update a user (partial)
PATCH /users/123
{"name": "Alice Smith"}

# List a user's orders (nested resource)
GET /users/123/orders?status=pending&page=2&limit=20

# Delete a user
DELETE /users/123

• Stateless: Each request contains all information needed to process it. No server-side session state.
• Uniform interface: Consistent URL structure and HTTP verb semantics across all resources.
• Cacheable: GET responses can be cached. REST's alignment with HTTP makes CDN integration natural.
• Layered system: Clients don't need to know if they're talking to the server directly or via a proxy.

GraphQL

GraphQL was developed by Facebook to solve the over-fetching and under-fetching problems of REST. Clients send a query describing exactly what data they need, and the server returns precisely that — no more, no less.

# Client requests exactly the fields it needs
query {
  user(id: "123") {
    name
    email
    orders(status: PENDING) {
      id
      total
      items {
        productName
        quantity
      }
    }
  }
}

# Mutations change data
mutation {
  createUser(input: { name: "Alice", email: "alice@example.com" }) {
    id
    name
  }
}

# Subscriptions for real-time updates
subscription {
  orderStatusChanged(userId: "123") {
    orderId
    newStatus
  }
}

gRPC

gRPC (Google Remote Procedure Call) uses Protocol Buffers for serialization and HTTP/2 for transport. It generates client and server stubs in 10+ languages from a `.proto` schema file, making cross-language service communication type-safe and efficient.

// users.proto
syntax = "proto3";

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User); // server streaming
  rpc CreateUser (CreateUserRequest) returns (User);
}

message GetUserRequest {
  string user_id = 1;
}

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

Protocol Buffers produce binary payloads 5-10x smaller than equivalent JSON. HTTP/2 multiplexing allows multiple RPC calls over a single TCP connection. gRPC natively supports four communication patterns: unary (request-response), server streaming, client streaming, and bidirectional streaming.

API Versioning Strategies

APIs must evolve without breaking existing clients. The main versioning strategies are:

Pagination Patterns

When APIs return lists, pagination prevents responses from growing unbounded. Three main approaches exist: