API Design Principles

APIs
11 / 21

How to design APIs that are intuitive, versioned, consistent, and safe to evolve over time.

ClientsWeb clientMobile appEntry pointAPI GatewayAuth ยท Rate limitingRoutingServicesLLM serviceVector DBEmbedding API
SD blueprint: API Gateway Architecture
The Analogy (Read This First)

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.

Deep Dive Analysis

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.

Key Bullets
  • 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.
Real-World Examples
Stripe API: gold standard REST design (idempotency keys, versioning, webhooks)GitHub GraphQL API v4: complex relationship queries in one round-tripGoogle APIs: gRPC internally, REST/HTTP transcoding for external clients

Curated Curation & Deep Insights

ScaleDojo Certified
Video Tutorial Pending

Our system architects are vetting high-quality, authorized video guides for API Design Principles with zero third-party platform links.

Verification in Progress
Reading Material Pending

We are preparing premium, zero-competitor deep-dives for API Design Principles. Authorized reading references will appear automatically.

Verification in Progress
ScaleDojo Logo
Initializing ScaleDojo