API Design Principles
APIsHow to design APIs that are intuitive, versioned, consistent, and safe to evolve over time.
An API is like the menu at a restaurant. The menu is the contract: it lists what's available, what information you need to provide (ingredients excluded, allergies), and what you'll get back. A good menu is clear and consistent. A bad menu changes without notice, uses different naming conventions per page, and removes dishes you rely on.
REST (Representational State Transfer): The dominant style for public APIs. Resources are nouns (users, orders, products). Operations are HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE (remove). Stateless - each request contains all needed information. Use status codes correctly: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Server Error.
GraphQL: Clients specify exactly which fields they need in a single query. Solves over-fetching (REST endpoint returns 30 fields, you need 3) and under-fetching (needing multiple REST calls for related data). Used by GitHub API v4, Shopify, Airbnb. Trade-off: complex caching, potential N+1 query problems server-side.
gRPC: Google's RPC framework using Protocol Buffers (binary serialization). 5-7x faster than JSON. Strong typing via .proto files. Excellent for internal microservice communication where performance matters. Not browser-friendly without grpc-web.
API Versioning: Never break existing clients. Common strategies: URL path versioning (/api/v1/users), header versioning (API-Version: 2), query parameter versioning (?version=2). Maintain old versions for at least 6-12 months after deprecation.
Pagination: Never return unbounded lists. Cursor-based pagination (next_cursor token) is superior to offset pagination (page=1&size=10) for large datasets - cursor is stable when items are inserted/deleted mid-pagination.
Rate Limiting: Protect your API from abuse. Common algorithms: Fixed Window (100 req/minute per user), Sliding Window (more accurate, prevents boundary bursts), Token Bucket (allows short bursts). Return 429 Too Many Requests with Retry-After header.
- Idempotency tokens: POST /payments with Idempotency-Key header prevents double charges on retry.
- HATEOAS (optional): responses include links to related actions (rarely used in practice).
- Always validate input server-side - never trust clients.
- Use consistent error response shapes: { error: { code, message, details } }.
- Document with OpenAPI/Swagger - makes client generation and testing trivial.
Curated Curation & Deep Insights
ScaleDojo CertifiedOur system architects are vetting high-quality, authorized video guides for API Design Principles with zero third-party platform links.
We are preparing premium, zero-competitor deep-dives for API Design Principles. Authorized reading references will appear automatically.