APIs — the contracts between systems — System Design

🔌Key Takeaways

1
REST = resource-based URLs + HTTP methods; most common for public APIs
2
GraphQL = single endpoint, client specifies exact data shape; great for complex UIs
3
gRPC = binary Protocol Buffers over HTTP/2; fastest for service-to-service communication
4
Idempotency keys prevent duplicate operations; rate limiting protects against abuse

APIs Are the Contracts of Distributed Systems

Every service in a distributed system communicates through APIs. The API defines what operations are available, what data is required, and what format responses use. A well-designed API is the difference between a system that's easy to evolve and one that becomes a maintenance nightmare.

API Styles Compared

REST (Representational State Transfer) uses standard HTTP methods on resource URLs. GET /users/123 retrieves user 123. POST /users creates a new user. PUT /users/123 updates. DELETE /users/123 deletes.

Pros: Simple, widely understood, excellent tooling, cacheable. Cons: Over-fetching (get all fields when you need 2), under-fetching (need 3 requests to assemble a view).

Best for: Public APIs, CRUD-heavy applications, when simplicity matters.

REST vs GraphQL vs gRPC

Feature	REST	GraphQL	gRPC
Format	JSON	JSON	Protocol Buffers (binary)
Transport	HTTP/1.1 or 2	HTTP	HTTP/2
Caching	Built-in (HTTP cache)	Custom	Limited
Schema	OpenAPI (optional)	Required (SDL)	Required (.proto)
Streaming	No (SSE workaround)	Subscriptions	Native bidirectional
Code generation	Optional	Yes	Yes (strong)
Best for	Public APIs	Complex client UIs	Internal microservices

REST API Design Example

# Good REST API Design
GET    /api/v1/users              # List users (with pagination)
GET    /api/v1/users/123          # Get single user
POST   /api/v1/users              # Create user
PUT    /api/v1/users/123          # Full update
PATCH  /api/v1/users/123          # Partial update  
DELETE /api/v1/users/123          # Delete user

# Pagination: GET /api/v1/users?page=2&limit=20
# Filtering: GET /api/v1/users?role=admin&active=true
# Sorting:   GET /api/v1/users?sort=-created_at

# Idempotency key (prevent duplicate POST):
POST /api/v1/orders
Headers: Idempotency-Key: abc-123-def-456

💡Rate Limiting

Protect your API with rate limiting. Common strategies: fixed window (100 req/min), sliding window (smoother), token bucket (burst-friendly). Return HTTP 429 Too Many Requests when limit exceeded. Include X-RateLimit-Remaining header so clients can self-throttle.

Advantages

•APIs enable independent service development and deployment
•Well-designed APIs are self-documenting and discoverable
•Multiple API styles let you pick the right tool for each use case

Disadvantages

•API versioning is always messy (v1, v2, or header versioning?)
•Breaking changes can cascade across the entire system
•Over-abstraction leads to chatty APIs with too many round trips

🧪 Test Your Understanding

Knowledge Check1/2

Which API style is best for internal microservice-to-microservice communication?

APIs — the contracts between systems