Design Paradigms

A design paradigm is the communication style your API uses. Just like humans communicate differently depending on context — a formal letter, a quick text, a phone call, a live conversation — APIs have different paradigms optimized for different situations.

There is no single "best" paradigm. Each one exists because it solves a specific set of problems better than the others. The skill is knowing which one to reach for and why.

Before diving deep into each paradigm, here's the mental model. Think of two axes: flexibility vs performance, and request-response vs streaming.

Need a simple CRUD API?                    → REST
Need flexible queries for complex UIs?      → GraphQL
Need fast internal service communication?   → gRPC
Need real-time bidirectional data?           → WebSockets

Still unsure? Start with REST.
It's the simplest, most understood, most cacheable option.
Only move to another paradigm when REST's limitations hurt you.

REST (Representational State Transfer) is the most widely used API paradigm on the web. It treats everything as a resource identified by a URL, and uses standard HTTP methods to operate on those resources.

Core Principles

URL Structure & HTTP Methods

Products:
  GET    /api/products          → List all products
  GET    /api/products/42       → Get product #42
  POST   /api/products          → Create a new product
  PUT    /api/products/42       → Replace product #42 entirely
  PATCH  /api/products/42       → Update specific fields of product #42
  DELETE /api/products/42       → Delete product #42

Orders:
  GET    /api/users/7/orders    → List orders for user #7
  POST   /api/orders            → Create a new order
  GET    /api/orders/101        → Get order #101
  PATCH  /api/orders/101        → Update order #101 (e.g., cancel)

Nested Resources:
  GET    /api/orders/101/items  → List items in order #101

Status Codes — Speak HTTP

Idempotency — Why It Matters

An operation is idempotent if calling it multiple times produces the same result as calling it once. This is critical for reliability — if a network request times out, the client can safely retry without causing duplicates.

GraphQL is a query language for APIs. Instead of the server deciding what data to return (like REST), the client specifies exactly what it needs. One request, one endpoint, precisely the data you asked for.

How GraphQL Works

REST approach (3 requests):
  GET /api/users/42           → { id, name, email, avatar, bio, ... }
  GET /api/users/42/orders    → [{ id, total, status, items, ... }, ...]
  GET /api/orders/101/reviews → [{ id, rating, comment, ... }, ...]

GraphQL approach (1 request):
  POST /graphql
  {
    user(id: 42) {
      name
      email
      orders(last: 5) {
        id
        total
        reviews {
          rating
        }
      }
    }
  }

Response — exactly what was asked:
  {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "orders": [
        {
          "id": "101",
          "total": 59.99,
          "reviews": [{ "rating": 5 }]
        }
      ]
    }
  }

Real-World Use Case: Dashboard

Imagine a dashboard that shows a user's profile, their recent orders, top products, and notification count — all on one page. With REST, that's 4+ API calls. With GraphQL, it's one query that fetches exactly the fields each widget needs. This is where GraphQL shines: complex UIs that aggregate data from multiple sources.

gRPC is a high-performance RPC (Remote Procedure Call) framework built by Google. Instead of sending JSON over HTTP like REST, gRPC sends binary data (Protocol Buffers) over HTTP/2. It's designed for fast, efficient communication between services.

Protocol Buffers (Protobuf)

Protobuf is the serialization format gRPC uses. You define your data structures and service methods in a.protofile, and a code generator creates typed client and server code in your language of choice.

syntax = "proto3";

package user;

// The data structure
message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
  repeated Order orders = 4;
}

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

// The service definition
service UserService {
  // Unary — one request, one response
  rpc GetUser(GetUserRequest) returns (User);

  // Server streaming — one request, stream of responses
  rpc ListOrders(ListOrdersRequest) returns (stream Order);

  // Client streaming — stream of requests, one response
  rpc UploadLogs(stream LogEntry) returns (UploadResult);

  // Bidirectional streaming — both sides stream
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message GetUserRequest { int32 id = 1; }
message ListOrdersRequest { int32 user_id = 1; }
message LogEntry { string message = 1; int64 timestamp = 2; }
message UploadResult { int32 count = 1; }
message ChatMessage { string text = 1; string sender = 2; }

Communication Types

Why Binary? JSON vs Protobuf

WebSocket APIs provide a persistent, full-duplex communication channel between client and server. Unlike REST (where the client always initiates), WebSockets let the server push data to the client at any time without being asked.

How WebSocket APIs Differ from HTTP

Real-World Use Cases

WebSockets vs Polling vs Long Polling vs SSE

The real skill isn't knowing what each paradigm does — it's knowing which one to pick for a given system. Let's walk through real scenarios.

💬 Scenario: Chat Application

Choose: WebSockets for real-time messaging + REST for everything else

Why WebSockets: Messages must appear instantly for all participants. The server needs to push messages without the client asking. Bidirectional — both sides send messages.

Why REST alongside: User registration, login, fetching chat history, uploading files — these are all standard request-response operations. No need for WebSockets here.

Architecture: REST API for CRUD + WebSocket server for real-time messaging + Redis Pub/Sub for broadcasting across server instances.

🛒 Scenario: E-Commerce Backend

Choose: REST for public API + GraphQL for the storefront

Why REST: Product catalog, order management, payment processing — these are classic CRUD operations. REST is simple, cacheable (product pages via CDN), and well-understood by third-party integrators.

Why GraphQL for storefront: The product page needs product details + reviews + related products + inventory status. With REST, that's 4 requests. With GraphQL, it's one query. Mobile app gets a lighter payload by requesting fewer fields.

Architecture: REST API for backend services + GraphQL BFF (Backend for Frontend) that aggregates REST calls for the storefront.

📈 Scenario: Real-Time Stock Trading App

Choose: WebSockets for price feeds + gRPC for internal services + REST for account management

Why WebSockets: Stock prices change multiple times per second. The server must push updates instantly. Even 100ms of delay can mean a different price.

Why gRPC internally: The pricing engine, order matching engine, and risk service communicate millions of times per second. Protobuf's binary format and gRPC's streaming make this feasible. JSON would be too slow.

Why REST for accounts: Login, account settings, transaction history — low-frequency CRUD. REST is the simplest choice.

🔧 Scenario: Microservices Internal Communication

Choose: gRPC

Why: Internal services don't need human-readable JSON. They need speed, strong typing, and streaming. gRPC's code generation ensures type safety across services in different languages. Protobuf is 3-10x smaller than JSON. HTTP/2 multiplexing handles high concurrency.

Why not REST: JSON serialization overhead adds up at millions of requests/second. No streaming support. No built-in code generation.

Architecture: gRPC between all internal services + REST or GraphQL gateway for external clients.

Every paradigm choice is a trade-off. Here are the key comparisons you need for interviews.

REST vs GraphQL

GraphQL vs gRPC

WebSockets vs HTTP

Conceptual, scenario-based, and comparison questions you're likely to encounter.

These misconceptions trip up engineers in interviews and in real architectural decisions.