System Design Module 10: API Design & Rate Limiting

Introduction to API Design

In a microservices architecture, the API is the contract between your services. A well-designed API is easy to use, hard to misuse, and evolves without breaking existing clients.

1. REST vs. gRPC

REST (Representational State Transfer): Uses HTTP/1.1 and JSON. Standard for external-facing web APIs.
gRPC: Uses HTTP/2 and Protocol Buffers (Binary). Fast, efficient, and typed. Standard for internal microservice communication.

2. API Versioning

Never break your clients. Use versioning:

Path-based: api.v1.example.com or example.com/v1/
Header-based: Accept: application/vnd.example.v1+json

3. Idempotency in API Design

An idempotent API ensures that making the same call multiple times has the same effect as making it once.

GET, PUT, DELETE: Should be idempotent by default.
POST: Use an Idempotency-Key to guarantee safety.

4. Rate Limiting Strategies

Rate limiting protects your API from being overwhelmed.

Client-side: Throttling requests before they leave the browser/app.
Server-side: Blocking requests at the API Gateway.
Algorithms: Token Bucket, Leaky Bucket, Sliding Window. (See the Case Study for details).

5. Trade-offs (JSON vs Protobuf)

JSON: Human-readable, easy to debug, but slow to parse and larger in size.
Protobuf: Binary, fast to parse, strictly typed, but requires special tooling to read.

Final Takeaway

An API is a Commitment. Once you expose it to the world, it is very hard to change. Design with the future in mind.