Designing API Architecture
1. Designing RESTful API Principles
| Principle | Description |
|---|---|
| Resource-oriented | Nouns in URI: /users/123/orders |
| Uniform interface | Standard HTTP verbs + status codes |
| Stateless | No server-side session state |
| Cacheable | Cache-Control / ETag |
| Layered | Proxies/CDN transparent |
| HATEOAS | Hypermedia links (optional) |
2. Designing GraphQL Architecture
| Component | Role |
|---|---|
| Schema (SDL) | Types, queries, mutations, subscriptions |
| Resolvers | Per-field data fetching |
| DataLoader | Batch + cache to solve N+1 |
| Federation | Compose subgraphs into supergraph |
| Subscriptions | WebSocket-based real-time |
3. Designing gRPC Services
| Feature | Detail |
|---|---|
| Transport | HTTP/2 multiplexed binary |
| Encoding | Protobuf (compact, schema) |
| Modes | Unary, server-stream, client-stream, bidi |
| Browser | Needs grpc-web proxy |
| Best for | Internal service-to-service, low latency |
4. Designing API Versioning Strategy
| Strategy | Example |
|---|---|
| URI | /v1/users, /v2/users |
| Header | Accept: application/vnd.api.v2+json |
| Query param | ?version=2 |
| No version | Additive-only changes (Stripe-like) |
5. Designing API Rate Limiting Architecture
| Layer | Where Enforced |
|---|---|
| Edge | CDN/WAF (DDoS, IP-based) |
| Gateway | API key, tenant tier |
| Service | Endpoint-specific or operation-cost-based |
| DB | Resource-protective limits |
6. Designing API Authentication Architecture
| Method | Use Case |
|---|---|
| JWT (Bearer) | Stateless, microservices |
| OAuth2 / OIDC | Third-party login, delegation |
| API Key | Server-to-server, simple integrations |
| mTLS | Internal service mesh |
| HMAC | AWS SigV4-style request signing |
7. Designing API Gateway Architecture
| Function | Detail |
|---|---|
| Routing | Path/host → service |
| AuthN/Z | JWT validation, scopes |
| Rate limiting | Per key/tenant |
| Transformation | Header rewrite, response shaping |
| Aggregation | Compose multiple service calls |
| Tools | Kong, Apigee, Tyk, AWS API GW, Envoy, Krakend |
8. Designing Pagination Strategy
| Type | Pros | Cons |
|---|---|---|
| Offset/Limit | Simple, jump to page | Slow for large offsets, drift on inserts |
| Cursor (keyset) | Stable, fast O(log n) | No random page jump |
| Page token | Opaque cursor | Server-defined |
| Time-based | Streams | Need monotonic timestamp |
Example: Cursor pagination
SELECT id, created_at, name
FROM users
WHERE (created_at, id) < ($cursor_ts, $cursor_id)
ORDER BY created_at DESC, id DESC
LIMIT 20;9. Designing API Throttling
| Policy | Behavior |
|---|---|
| Reject (429) | Hard cap; client retries |
| Queue | Buffer + bounded delay |
| Shape | Smooth bursts (token bucket) |
| Tier-based | Free vs Pro vs Enterprise quotas |
10. Designing API Documentation Strategy
| Tool | Use |
|---|---|
| OpenAPI 3.1 | REST spec; codegen |
| AsyncAPI | Event-driven APIs |
| GraphQL SDL | Self-documenting + introspection |
| Protobuf | gRPC; auto docs (buf.build) |
| Portal | Redoc, SwaggerUI, Stoplight, Scalar |
11. Designing HATEOAS Principles
Example: HATEOAS response
{
"id": 42,
"status": "pending",
"_links": {
"self": { "href": "/orders/42" },
"cancel": { "href": "/orders/42/cancel", "method": "POST" },
"ship": { "href": "/orders/42/ship", "method": "POST" }
}
}| Benefit | Drawback |
|---|---|
| Discoverable state transitions | Verbose; few clients leverage links |
| Decouples client from URL structure | Increases payload size |
12. Designing Idempotent API Architecture
| Element | Detail |
|---|---|
| Idempotency-Key header | Client UUID per logical op |
| Storage TTL | 24h+ for financial APIs |
| Response replay | Same key returns cached response |
| Conflict | 409 if request body differs for same key |