API Design Vocabulary

REST (Representational State Transfer) is an architectural style defined by Roy Fielding. Key constraints: stateless (each request contains all the info the server needs — no session stored server-side), resource-based (URLs identify resources: /users/42, not /getUser?id=42), uniform interface (standard HTTP verbs — GET reads, POST creates, PUT/PATCH updates, DELETE removes). A RESTful API follows these constraints. Common vocabulary in API discussions: endpoint (a specific URL + method), resource (the noun — user, order, product), representation (the JSON/XML sent over the wire), HATEOAS (Hypermedia as the Engine of Application State — responses include links to related actions). Contrasted with: GraphQL (option C) and gRPC (option A).

GraphQL (developed at Facebook, open-sourced 2015) solves over-fetching and under-fetching. A GraphQL client sends a query specifying exactly the fields it needs: { product { name price thumbnail } } — only those fields are returned. Over-fetching: REST returns too many fields (wasted bandwidth — especially painful on mobile). Under-fetching: REST requires multiple requests to get all needed data (N+1 problem — also solved by GraphQL's nested queries). Key vocabulary: schema (type definitions — the contract), query (read operation), mutation (write operation), subscription (real-time updates via WebSocket), resolver (function that fetches data for a field), introspection (clients can query the schema itself). Trade-off: GraphQL is more complex to cache (every request is POST to a single endpoint).

Idempotency: calling an operation once produces the same outcome as calling it N times. This matters for fault-tolerant clients: if the network fails after the server processes a request but before the client receives the response, the client can safely retry an idempotent operation. HTTP method idempotency: GET ✅ (read, no state change), PUT ✅ (replace resource — calling twice gives the same state), DELETE ✅ (deleting a deleted resource is still "deleted"), POST ❌ (not idempotent — submitting an order form twice creates two orders). Safe methods (no side effects): GET, HEAD. Idempotent but not safe: PUT, DELETE. Neither safe nor idempotent: POST. Practical tip: use idempotency keys (a unique client-generated ID sent with the request) to make POST endpoints idempotent — Stripe does this for payment requests.

Rate limiting controls how many requests a client can make in a given time window to protect the API from abuse, ensure fair usage, and prevent resource exhaustion. HTTP 429 = "Too Many Requests." Common strategies: fixed window (1,000 req/hour resets at :00), sliding window (any 60-minute window — smoother), token bucket (replenishes tokens at a fixed rate — allows controlled bursts), leaky bucket (processes requests at a fixed rate — smooths spikes). Response headers: X-RateLimit-Limit (total limit), X-RateLimit-Remaining (remaining in current window), X-RateLimit-Reset (when window resets, Unix timestamp), Retry-After (seconds to wait). Rate limiting per client can be keyed by: API key, IP address, user ID, OAuth scope. Related: throttling (slowing requests down rather than blocking them), quota (longer-term total limit — e.g., 1M req/month).

API versioning lets you evolve an API without breaking existing clients. The four common strategies: (1) URL path (/v2/users) — most common, explicit, easily testable in a browser, visible in logs; (2) Query parameter (?version=2) — less clean, works but pollutes query strings; (3) Header versioning (Accept: application/vnd.myapi.v2+json or X-API-Version: 2) — clean URLs but harder to test, invisible in browser. URL path versioning is preferred for public APIs (it's explicit and discoverable). When to version: when you make a breaking change (removing fields, renaming fields, changing data types, removing endpoints). Non-breaking additions (new optional fields, new endpoints) generally don't need a version bump. Key vocabulary: breaking change, backward compatibility, deprecation notice, sunset header (HTTP header indicating when an old version will stop working).