System Designer
Back to Technology

API Paradigms

Master different API architectural styles and when to use each approach

25 min read•
Not Started

API Performance & Complexity Calculator

50 endpoints
1000 RPS
3 client types

Performance Metrics

Average Latency:50 ms
Throughput:333 RPS
Bandwidth Usage:3.91 MB/s
Protocol Overhead:-20%

Caching & Optimization

Cache Hit Rate:63%
Bandwidth Saved:2.46 MB/s
Cacheability:90%

Development & Maintenance

Maintenance Score:99/100
Type Safety:Medium
Horizontal Scaling:Excellent
Security Complexity:Medium

API Paradigms Overview

Different API paradigms solve different problems and have unique trade-offs in terms of performance, complexity, and use cases. Understanding when to use each approach is crucial for building effective distributed systems.

Request-Response

Synchronous communication where clients request data and servers respond (REST, GraphQL, gRPC).

Event-Driven

Asynchronous communication through events and callbacks (Webhooks, Message Queues).

Real-time

Bidirectional, persistent connections for low-latency communication (WebSockets, Server-Sent Events).

REST (Representational State Transfer)

Core Principles

Stateless

Each request contains all necessary information

Resource-Based

URLs represent resources, not actions

HTTP Methods

GET, POST, PUT, DELETE for CRUD operations

# REST API examples
GET /api/users/123
POST /api/users
PUT /api/users/123
DELETE /api/users/123
# Clear resource-based URLs

Advantages & Disadvantages

✓ Advantages:
  • Simple and intuitive
  • Great caching support
  • Stateless and scalable
  • Wide tooling support
  • HTTP status codes
✗ Disadvantages:
  • Over-fetching and under-fetching
  • Multiple round trips for related data
  • Versioning challenges
  • Limited real-time capabilities
  • No built-in type safety

REST Maturity Model

0
POX (Plain Old XML):Single endpoint, HTTP as transport
1
Resources:Multiple endpoints, resource-based URLs
2
HTTP Verbs:Proper use of GET, POST, PUT, DELETE
3
Hypermedia (HATEOAS):Self-describing APIs with links

GraphQL

Query Language Features

GraphQL allows clients to request exactly the data they need with a single endpoint and flexible queries.

• Single endpoint: /graphql
• Flexible queries: Request specific fields
• Strong typing: Schema-defined types
• Introspection: Self-documenting
# GraphQL query
query {
user(id: "123") {
name
email
posts {
title
createdAt
}
}
}

Core Concepts

Queries

Read operations to fetch data from the server.

Mutations

Write operations to modify data on the server.

Subscriptions

Real-time data updates through WebSocket connections.

Challenges & Solutions

N+1 Query Problem

Resolvers making multiple database calls instead of efficient joins.

Solutions: DataLoader, query batching, database joins in resolvers

Query Complexity

Malicious or complex queries can overwhelm servers.

Solutions: Query depth limiting, complexity analysis, timeouts

gRPC (gRPC Remote Procedure Calls)

Protocol Buffers & Performance

gRPC uses Protocol Buffers for efficient serialization and HTTP/2 for multiplexing, providing high performance for microservice communication.

• Binary protocol: Smaller payloads
• HTTP/2: Multiplexing, server push
• Code generation: Type-safe clients
• Streaming: Bidirectional data flow
# Protocol Buffer definition
service UserService {
rpc GetUser(UserRequest)
returns (UserResponse);
rpc ListUsers(Empty)
returns (stream UserResponse);
}
# Generates type-safe code

Communication Patterns

Unary RPC

Simple request-response like REST

Server Streaming

Server sends multiple responses

Client Streaming

Client sends multiple requests

Bidirectional Streaming

Both sides stream data

Use Cases & Limitations

✓ Best For:
  • Microservice communication
  • High-performance APIs
  • Real-time streaming
  • Polyglot environments
  • Mobile backends
✗ Limitations:
  • Browser support requires grpc-web
  • Limited debugging tools
  • Binary format not human-readable
  • Protocol Buffer learning curve
  • Less caching support

Event-Driven APIs

Webhooks

HTTP callbacks that notify clients when events occur, enabling real-time updates without constant polling.

• Event-driven: Push notifications
• Efficient: No polling overhead
• Scalable: Decoupled architecture
• Reliable: Retry mechanisms
# Webhook payload
POST /webhook/payment HTTP/1.1
Content-Type: application/json
{
"event": "payment.completed",
"data": {
"id": "pay_123",
"amount": 2500
}
}

Server-Sent Events (SSE)

One-way communication from server to browser using standard HTTP, ideal for live updates and notifications.

# SSE stream
data: {"message": "New order received"}
event: order
id: 1
data: {"status": "Order processing"}
event: status
id: 2
Benefits:
• Simple HTTP connection
• Auto-reconnection
• Built-in browser support
Use Cases:
• Live feeds and updates
• Real-time dashboards
• Progress notifications

WebSockets

Full-duplex communication protocol for real-time, interactive applications requiring low latency.

• Bidirectional: Client ↔ Server
• Low latency: No HTTP overhead
• Persistent: Long-lived connections
• Efficient: No request/response cycle
Perfect For:
Chat applications, gaming, collaborative editing, live trading
Challenges:
Connection management, scaling, proxy issues

API Paradigm Comparison

AspectRESTGraphQLgRPCWebSocket
Learning CurveLowMediumMediumHigh
PerformanceGoodVariableExcellentExcellent
CachingExcellentLimitedLimitedNone
Real-timePoorGoodExcellentExcellent
Type SafetyWeakStrongStrongWeak
Browser SupportNativeNativegrpc-webNative
ToolingMatureGoodGrowingBasic

Choosing the Right API Paradigm

🎯 REST is ideal for:

  • • Public APIs with wide compatibility
  • • CRUD operations on resources
  • • Cacheable read-heavy workloads
  • • Simple, stateless interactions

📊 GraphQL excels at:

  • • Flexible data fetching needs
  • • Multiple client types (mobile, web)
  • • Rapid frontend development
  • • Reducing API versioning complexity

⚡ gRPC works best for:

  • • High-performance microservices
  • • Streaming data requirements
  • • Type-safe service contracts
  • • Polyglot distributed systems

🔔 Event-driven APIs for:

  • • Real-time notifications
  • • Webhook integrations
  • • Decoupled architectures
  • • Event sourcing patterns

🔄 WebSockets for:

  • • Real-time chat and messaging
  • • Live collaborative editing
  • • Gaming and interactive apps
  • • Live data streaming

🔍 Decision Framework:

  • • Consider client diversity and needs
  • • Evaluate performance requirements
  • • Assess team expertise and tooling
  • • Plan for future scalability

📝 API Paradigms Knowledge Quiz

1 of 5Current: 0/5

Which API paradigm is best for exposing resources over HTTP?