HLD · APIs

API Design & Rate Limiting

Expose reliable APIs and protect backends from abuse and overload.

1. REST API design basics

• Resources as nouns: GET /users/123, POST /orders
• HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE
• Status codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Server Error
• Versioning: /v1/users or header Accept-Version
• Pagination: ?cursor=abc&limit=20 (preferred over offset at scale)

2. API Gateway role

Single entry point that handles:

• Authentication (JWT validation)
• Rate limiting & throttling
• Routing to microservices
• SSL termination, request logging, API keys

Examples: AWS API Gateway, Kong, NGINX, Envoy.

3. Why rate limiting

• Prevent abuse (scraping, brute force)
• Fair usage across tenants (free vs paid tier)
• Protect downstream (DB, payment provider caps)
• Cost control on serverless/metered APIs

Example: OpenAI API — 60 requests/min per API key. Excess returns 429 with Retry-After header.

4. Rate limiting algorithms

Token bucket

Bucket holds tokens; refills at fixed rate. Each request consumes 1 token. Allows bursts up to bucket size.

Example: 100 tokens, refill 10/sec → user can burst 100, then steady 10 RPS.

Leaky bucket

Requests enter queue; processed at constant rate. Smooths bursts; excess dropped or queued.

Fixed window

Count requests per minute. Simple but boundary spike (59 at :59 + 60 at :00 = 119 in 2 seconds).

Sliding window

Count over rolling last 60 seconds. Smoother; slightly more state (Redis sorted sets).

5. Distributed rate limiting

Multiple API servers must share counters → use Redis with atomic INCR + TTL or Lua scripts.

6. Idempotency for safe retries

Client sends Idempotency-Key: uuid on POST payment. Server stores result keyed by UUID — duplicate requests return same response without double charge.

7. GraphQL vs REST (brief)

REST: multiple endpoints, fixed payloads. GraphQL: single endpoint, client picks fields — flexible but harder to cache and rate-limit per resource.