API Design (REST, GraphQL, gRPC) in System Design

In the intricate landscape of system design, API design serves as the foundational communication layer that enables different components, services, and clients to interact seamlessly at scale. The choice of API paradigm directly influences performance, maintainability, scalability, and developer experience. Three dominant approaches dominate modern distributed systems: REST, GraphQL, and gRPC. Each addresses distinct challenges in data exchange, efficiency, and real-time capabilities while fitting specific architectural patterns such as microservices, event-driven architectures, and high-throughput applications.

REST API Design

REST, or Representational State Transfer, is an architectural style introduced by Roy Fielding that emphasizes a stateless, client-server model built on standard HTTP protocols. In system design, REST APIs excel when simplicity, cacheability, and broad compatibility are paramount. The core constraints of REST include client-server separation, statelessness, cacheability, uniform interface, layered system, and code on demand.

A REST API treats data as resources identified by URIs. Operations on these resources map to HTTP methods: GET for retrieval, POST for creation, PUT for full updates, PATCH for partial updates, and DELETE for removal. This mapping aligns with CRUD operations while enforcing idempotency where applicable—PUT and DELETE are idempotent, whereas POST is not.

HTTP status codes provide explicit feedback: 2xx for success, 4xx for client errors, and 5xx for server errors. REST leverages HTTP headers for metadata, such as Content-Type, Authorization, and Cache-Control. Versioning is typically handled via URI paths (/v1/users), headers, or query parameters to maintain backward compatibility in evolving systems.

Here is a complete, production-ready REST API implementation using Node.js and Express to illustrate resource management for a user service in a microservices environment:

const express = require('express');
const app = express();
app.use(express.json());

// In-memory store for demonstration (replace with database in production)
let users = [{ id: 1, name: 'Alice', email: '[e-mail]' }];

// GET all users - retrieval with optional pagination and filtering
app.get('/api/v1/users', (req, res) => {
  const { page = 1, limit = 10 } = req.query;
  const startIndex = (page - 1) * limit;
  const paginatedUsers = users.slice(startIndex, startIndex + parseInt(limit));
  res.status(200).json({
    data: paginatedUsers,
    meta: { total: users.length, page: parseInt(page), limit: parseInt(limit) }
  });
});

// GET single user by ID - resource-specific endpoint
app.get('/api/v1/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.status(200).json(user);
});

// POST create user - non-idempotent creation with validation
app.post('/api/v1/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) return res.status(400).json({ error: 'Name and email required' });
  const newUser = { id: users.length + 1, name, email };
  users.push(newUser);
  res.status(201).json(newUser);
});

// PUT full update - idempotent
app.put('/api/v1/users/:id', (req, res) => {
  const userIndex = users.findIndex(u => u.id === parseInt(req.params.id));
  if (userIndex === -1) return res.status(404).json({ error: 'User not found' });
  users[userIndex] = { id: parseInt(req.params.id), ...req.body };
  res.status(200).json(users[userIndex]);
});

// PATCH partial update
app.patch('/api/v1/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  Object.assign(user, req.body);
  res.status(200).json(user);
});

// DELETE user - idempotent removal
app.delete('/api/v1/users/:id', (req, res) => {
  const userIndex = users.findIndex(u => u.id === parseInt(req.params.id));
  if (userIndex === -1) return res.status(404).json({ error: 'User not found' });
  users.splice(userIndex, 1);
  res.status(204).send();
});

app.listen(3000, () => console.log('REST API running on port 3000'));

This snippet demonstrates stateless design—each request contains all necessary information. In a real system, integrate database indexing, caching with Redis, and rate limiting at the API gateway level for horizontal scaling.

GraphQL API Design

GraphQL is a query language and runtime for APIs created by Facebook that allows clients to request exactly the data they need in a single round trip, eliminating over-fetching and under-fetching common in REST. In system design, GraphQL shines in complex, hierarchical data models and client-driven microservices where flexibility is essential.

The GraphQL schema defines types, queries, mutations, and subscriptions using Schema Definition Language (SDL). A single endpoint (/graphql) handles all operations via POST requests containing a query or mutation document. Resolvers map fields to data-fetching logic, enabling nested queries without multiple HTTP calls.

GraphQL supports introspection for self-documentation and subscriptions over WebSockets for real-time updates. Batching and caching at the resolver level prevent N+1 query problems using tools like DataLoader.

Here is a complete GraphQL setup using Node.js with Apollo Server and an in-memory store, showcasing a user service with nested relationships:

const { ApolloServer, gql } = require('apollo-server');

// Schema definition
const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
    posts: [Post!]!
  }
  type Post {
    id: ID!
    title: String!
    content: String!
    author: User!
  }
  type Query {
    users: [User!]!
    user(id: ID!): User
  }
  type Mutation {
    createUser(name: String!, email: String!): User!
  }
  type Subscription {
    userCreated: User!
  }
`;

// Resolvers with DataLoader pattern for N+1 prevention (simplified)
const users = [{ id: '1', name: 'Alice', email: '[e-mail]', posts: ['101'] }];
const posts = [{ id: '101', title: 'GraphQL Basics', content: 'Deep dive...', authorId: '1' }];

const resolvers = {
  Query: {
    users: () => users,
    user: (_, { id }) => users.find(u => u.id === id)
  },
  Mutation: {
    createUser: (_, { name, email }) => {
      const newUser = { id: String(users.length + 1), name, email, posts: [] };
      users.push(newUser);
      return newUser;
    }
  },
  User: {
    posts: (parent) => posts.filter(p => parent.posts.includes(p.id))
  }
};

const server = new ApolloServer({ typeDefs, resolvers });
server.listen().then(({ url }) => console.log(`GraphQL server ready at ${url}`));

This structure centralizes data fetching while giving clients precise control. In distributed systems, GraphQL integrates with API gateways for schema stitching across microservices and rate limiting per operation complexity.

gRPC API Design

gRPC is a high-performance, open-source RPC framework developed by Google that uses HTTP/2 for transport and Protocol Buffers for binary serialization. In system design, gRPC is preferred for internal service-to-service communication in polyglot microservices due to its low latency, built-in streaming, and strong typing.

gRPC contracts are defined in .proto files, which generate client and server stubs in multiple languages. It supports four communication patterns: unary, server streaming, client streaming, and bidirectional streaming. HTTP/2 multiplexing enables concurrent requests over a single connection, with automatic flow control and header compression.

Here is a complete gRPC definition and implementation example using a .proto file for a user service, followed by a Python server snippet:

syntax = "proto3";

package users;

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
  rpc ListUsers (stream Pagination) returns (stream UserResponse);
  rpc CreateUser (UserCreateRequest) returns (UserResponse);
  rpc StreamUserUpdates (stream UserUpdate) returns (stream UserResponse);
}

message UserRequest {
  string id = 1;
}

message Pagination {
  int32 page = 1;
  int32 limit = 2;
}

message UserCreateRequest {
  string name = 1;
  string email = 2;
}

message UserResponse {
  string id = 1;
  string name = 2;
  string email = 3;
}

message UserUpdate {
  string id = 1;
  string field = 2;
  string value = 3;
}

Corresponding Python server using grpcio (full implementation):

import grpc
from concurrent import futures
import users_pb2
import users_pb2_grpc

class UserService(users_pb2_grpc.UserServiceServicer):
    def GetUser(self, request, context):
        # Simulate database lookup
        return users_pb2.UserResponse(id=request.id, name="Alice", email="[e-mail]")

    def ListUsers(self, request_iterator, context):
        for pagination in request_iterator:
            # Stream users with pagination
            for i in range(pagination.limit):
                yield users_pb2.UserResponse(id=str(i), name=f"User{i}", email=f"user{i}@example.com")

    def CreateUser(self, request, context):
        return users_pb2.UserResponse(id="new123", name=request.name, email=request.email)

    def StreamUserUpdates(self, request_iterator, context):
        for update in request_iterator:
            yield users_pb2.UserResponse(id=update.id, name="Updated", email="[e-mail]")

server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
users_pb2_grpc.add_UserServiceServicer_to_server(UserService(), server)
server.add_insecure_port('[::]:50051')
server.start()
server.wait_for_termination()

gRPC leverages binary format for smaller payloads and native streaming for real-time scenarios, making it ideal for low-latency distributed systems. Service discovery and load balancing integrate naturally with Kubernetes and Istio.

Choosing the Right API Design in System Design

REST prioritizes simplicity and caching for public-facing APIs where broad client support matters. GraphQL solves data flexibility challenges in frontend-heavy applications and complex data graphs. gRPC delivers superior performance and strict contracts for internal microservices communication, especially under high load or with polyglot teams.

Trade-offs include REST’s verbosity versus GraphQL’s query complexity management and gRPC’s ecosystem maturity. In a complete system, hybrid approaches are common: REST for external clients, GraphQL for mobile/web, and gRPC for backend service meshes. Security considerations—OAuth, JWT, mTLS—apply uniformly, while observability tools like distributed tracing ensure reliability across paradigms.

For a comprehensive guide that builds upon these foundations and covers the full spectrum of system design principles, purchase the System Design Handbook at https://codewithdhanian.gumroad.com/l/ntmcf. Your purchase directly supports the creation of in-depth technical content. Buy me a coffee to support my content at: https://ko-fi.com/codewithdhanian.