API Design | System Design Library

REST

REST (Representational State Transfer) is the dominant API paradigm for web services. It uses standard HTTP methods and treats everything as a resource.

Core Principles

Stateless: Each request is self-contained; the server holds no session state
Resource-oriented: APIs are organized around nouns (resources), not actions
Standard methods: Use HTTP verbs to express intent

HTTP Verbs

| Verb | Operation | Idempotent? | |---|---|---| | GET | Read a resource | Yes | | POST | Create a resource | No | | PUT | Replace a resource | Yes | | PATCH | Partial update | No | | DELETE | Remove a resource | Yes |

REST URL Design

GET    /users              # List users
GET    /users/123          # Get user 123
POST   /users              # Create a new user
PUT    /users/123          # Replace user 123
PATCH  /users/123          # Update fields of user 123
DELETE /users/123          # Delete user 123
GET    /users/123/posts    # Get posts for user 123

HTTP Status Codes

2xx Success: 200 OK, 201 Created, 204 No Content
3xx Redirect: 301 Moved Permanently, 304 Not Modified
4xx Client Error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests
5xx Server Error: 500 Internal Server Error, 503 Service Unavailable

GraphQL

GraphQL lets clients request exactly the data they need — nothing more, nothing less.

query {
  user(id: "123") {
    name
    email
    posts(last: 5) {
      title
      createdAt
    }
  }
}

Pros:

No over-fetching (getting more data than needed)
No under-fetching (needing multiple requests to get all data)
Strong type system and self-documenting schema
Ideal for complex, nested data and mobile clients

Cons:

Complex to implement and cache (POST-based, not cacheable by default)
N+1 query problem requires DataLoader-style batching
Overkill for simple CRUD APIs

Best for: APIs consumed by multiple clients with different data needs (iOS, Android, web)

gRPC

gRPC is a high-performance RPC framework using Protocol Buffers (binary serialization) over HTTP/2.

Pros:

~5-10x faster than JSON/REST for serialization
Strong typing with .proto schema definitions
Streaming support (client, server, and bidirectional)
Auto-generates client/server code in many languages

Cons:

Binary format is not human-readable (harder to debug)
Limited browser support (requires grpc-web proxy)
More complex setup

Best for: Internal microservice-to-microservice communication

Comparison

| Feature | REST | GraphQL | gRPC | |---|---|---|---| | Format | JSON | JSON | Binary (Protobuf) | | Performance | Good | Good | Excellent | | Caching | Easy (HTTP) | Hard | Hard | | Type safety | No (unless OpenAPI) | Yes | Yes | | Browser support | Native | Native | Limited | | Learning curve | Low | Medium | High | | Best for | Public APIs | Complex client needs | Internal services |

API Versioning

Never break existing clients. Common versioning strategies:

URL versioning: /api/v1/users (simple, explicit)
Header versioning: Accept: application/vnd.api+json;version=1
GraphQL: Use deprecation annotations instead of versions

Interview Tips

Default to REST for most system design answers. Mention gRPC for internal microservice communication where performance matters
Know idempotency: GET and PUT are idempotent; POST is not. This matters for retry logic
Pagination is almost always needed: discuss cursor-based (stable, handles inserts/deletes) vs. offset-based (simple but can miss items)
API gateways (like AWS API Gateway or Kong) provide cross-cutting concerns: auth, rate limiting, routing, logging

NetworkingAPI Design