API Design

Good API design rests on five pillars:

1. Resource modeling: model the API around nouns (resources), not verbs (actions). /users, /orders, /orders/{id}/items — not /createOrder or /getUserData.
2. Versioning: APIs change. Version them from day one (/v1/...) so you can introduce breaking changes without breaking existing clients.
3. Pagination: list endpoints must paginate. Returning 100k records in one response is broken.
4. Error handling: consistent, structured error responses with meaningful codes and messages.
5. Idempotency: write operations should be safe to retry. POST without idempotency is a bug waiting to happen.

REST (Representational State Transfer) is the dominant style. It maps HTTP verbs to actions: GET (read), POST (create), PUT/PATCH (update), DELETE (delete). The URL identifies the resource; the verb identifies the action.

API versioning is non-negotiable for public APIs. Three approaches:

• URI versioning (/v1/users): the most common and the most explicit. Clients see the version in every request; routing is trivial. Downside: version in URL is "ugly" to some and breaks the principle that URLs are resource identifiers.
• Header versioning (Accept: application/vnd.api+json; version=1): cleaner URLs, version is a content negotiation. Downside: invisible in logs and tests; harder to route.
• Query parameter (/users?version=1): easy but mixes version with filtering. Generally discouraged.

The Stripe / GitHub / Twitter pattern: URI versioning. The cost of "ugly" URLs is far less than the cost of invisible versions. Most teams pick URI versioning and never look back.

When to bump the version: any breaking change. New endpoints, new fields, new optional parameters — no version bump needed. Removing or renaming fields, changing types, changing semantics — version bump. Maintain old versions for a deprecation window (6-24 months) so clients can migrate.

List endpoints must paginate. Three styles:

• Offset/limit (?offset=100&limit=20): the simplest. SQL-friendly. Problem: skipping is O(N) in many databases, and items shift if data changes between pages.
• Cursor-based (?cursor=abc123&limit=20): the cursor encodes the position (typically the last seen ID + sort key). Stable across inserts/deletes; O(1) skip in databases. The right choice for most APIs.
• Page-based (?page=5&per_page=20): user-friendly for UI but has the same problems as offset. Use only for low-volume, stable data.

Return pagination metadata in the response: next_cursor, has_more, total (if cheap to compute). Don't make clients guess whether there's another page.

Rate-limit list endpoints to reasonable page sizes (e.g., max 100 per page). A ?limit=1000000 request is a denial-of-service vector.

Idempotency makes APIs safe to retry — critical because networks fail and clients retry. HTTP spec defines GET, PUT, DELETE as idempotent; POST is not. But many POSTs should be idempotent (creating a charge, sending a message).

The fix is the Idempotency-Key header (Stripe's pattern, now widely adopted):

• Client generates a UUID per logical operation.
• Sends Idempotency-Key: <uuid> on the POST.
• Server stores the key + response for 24-48 hours.
• If the same key is sent again, server returns the stored response (not a new operation).

This makes POST safe to retry. Without it, a network timeout after the server created the charge but before the client received the response means a retry creates a duplicate. With it, the retry returns the original charge.

For non-idempotent operations (truly unique actions like "spin a slot machine"), don't accept an idempotency key — but document this clearly so clients know not to retry.

Mental model. Think of API Design as a deliberate boundary in a system. The boundary exists because something becomes harder to manage when everything is done in one place: latency, scale, failure isolation, consistency, cost, or team ownership. The useful question is not “what does API Design mean?” but “what pressure makes this boundary worth introducing, and what new failure mode does it create?”

Numerical lens: write down traffic, payload size, read/write ratio, peak multiplier and durability target before choosing a component. The numbers should justify the architecture.

Answer this without notes: When would you choose API Design, and when would you intentionally avoid it? Mention at least one bottleneck it addresses, one failure mode it introduces, and one alternative. Then quantify the workload you are designing for.

Numerical sanity check

Back-of-the-envelope reasoning beats fake precision. State your traffic, payload, concurrency and growth assumptions explicitly, then calculate enough to know whether the current architecture is orders of magnitude away from the target.