Interview Prep · Lesson 02

The API Design Cheat-Sheet

A portable, eight-step method for the whiteboard — plus the tables you'll reach for in every design interview. Open this once before an interview, then close it and go in confident.

The CREDO Method — 8 steps for any API design prompt

The acronym is just a memory aid; what matters is the logic flow. Use these eight steps in order. Don't skip ahead to endpoints before you've settled requirements — that's the single most common whiteboard mistake.

1. Clarify requirements & scale

   Before touching a whiteboard, ask. "How many requests per second at peak?" "Is this public or internal?" "Who are the consumers — mobile, browser, server, third-party?" "What's the latency target?" "What consistency model is required — eventually consistent is fine, or must reads always see the latest write?" Surface the constraints that will drive every later decision. Aim to spend 2–3 minutes here. Interviewers reward candidates who ask — it demonstrates production thinking.

   ✅ Questions to always ask

   • Expected read/write ratio and peak QPS?
   • Public API or internal only?
   • Multi-tenant (different orgs) or single-tenant?
   • Real-time (WebSocket) or request-response (HTTP)?
   • Idempotency requirement (payments, order placement)?
   • Any legal/compliance constraints (GDPR, PCI)?
2. Identify resources / entities

   List the nouns in the problem. "Design a food delivery API" → resources are: Customer, Restaurant, Menu, MenuItem, Order, OrderItem, Delivery, DeliveryPerson. Draw a simple entity map — which resources are top-level (have their own URI), which are sub-resources (live under a parent), and which are pure associations. Avoid verbs at this stage. Verbs become methods; nouns become resources. If you find yourself naming a resource with a verb (e.g., SendEmail), it probably belongs as an action on a noun resource (POST /emails).

3. Define endpoints & operations

   Map CRUD operations to HTTP methods for each top-level resource. Then handle non-CRUD actions (transitions, triggers) as POST to a sub-resource path (e.g., POST /orders/{id}/cancel rather than a verb in the main path). Decide on path conventions: plural nouns, lowercase, hyphens not underscores, hierarchy depth ≤ 3 levels. Confirm which endpoints are read-heavy (optimize for caching) and which are write-heavy (optimize for durability).

   # Example: Order resource CRUD + state transition
   POST   /v1/orders              # create
   GET    /v1/orders/{id}         # read one
   GET    /v1/orders              # list (paginated)
   PATCH  /v1/orders/{id}         # partial update
   DELETE /v1/orders/{id}         # remove (if allowed)
   POST   /v1/orders/{id}/cancel  # state transition

4. Request & response shapes

   For each endpoint, sketch the request body and response body. Use real field names, types, and formats. ISO 8601 for timestamps. Enums as strings, not magic integers. Avoid leaking internal column names or storage-layer types. For collections, always include a consistent envelope: { data: [...], next_cursor: "…", total_estimate: N }. For singletons, return the resource directly. Use consistent naming (snake_case or camelCase — pick one and never mix).

   # POST /v1/orders — request body
   {
     "restaurant_id": "rest_99",
     "items": [
       { "menu_item_id": "item_7", "quantity": 2 }
     ],
     "delivery_address_id": "addr_44"
   }
   
   # 201 Created — response body
   {
     "id": "ord_1234",
     "status": "pending",
     "created_at": "2026-06-20T10:00:00Z",
     "estimated_delivery_at": "2026-06-20T10:35:00Z"
   }

5. Errors & status codes

   Sketch the error contract as carefully as the success path. Use the right status code family (4xx = client fault, 5xx = server fault). Return a structured error body — a machine-readable code and a human-readable message at minimum: { "error": { "code": "ORDER_NOT_FOUND", "message": "Order ord_999 does not exist." } }. Never expose stack traces. Define the error catalog up front — interviewers notice when candidates treat errors as an afterthought.

6. Cross-cutting concerns

   This is where most interview answers fall short. Work through this checklist explicitly for every design:

   Concern	Default choice	When to deviate
   Authentication	Bearer token (OAuth 2.0 / JWT) in Authorization header	Machine-to-machine: API key + secret. Cookie auth only for same-site browser flows.
   Authorization	Check ownership inside every handler; never trust caller-supplied IDs alone	Add RBAC/ABAC for multi-role systems; use DB-level RLS for multi-tenant
   Idempotency	Require Idempotency-Key header on all mutating, non-replayable operations	Omit for pure read endpoints; skip if the operation is naturally idempotent (PUT, DELETE)
   Rate limiting	Per-client token bucket; return 429 + Retry-After	Separate limits for burst (per-second) vs sustained (per-day). Higher limits for trusted partners.
   Pagination	Cursor-based for large/live datasets	Offset for small static admin lists that need arbitrary page jumps
   Versioning	URI prefix: /v1/…	Header versioning for strict URL hygiene; use Deprecation + Sunset headers for lifecycle
   Caching	Set Cache-Control on GET responses; use ETags for conditional requests	Distributed cache (Redis) for read-heavy computed data; CDN edge cache for public read-heavy GETs
   Observability	Structured logs with trace ID on every request/response	Add metrics (p99 latency, error rate) per endpoint; distributed tracing (OpenTelemetry) for multi-service

7. Scale & latency budget

   Work back from the requirements you captured in step 1. State your latency target (e.g., "p99 under 200 ms") and trace where time is spent: network (client ↔ gateway ↔ service ↔ DB). Identify the hot path — the critical read or write endpoint that accounts for 80%+ of traffic — and explain how you'd scale it: read replicas, caching, sharding, CDN offload, async processing. Mention which operations require strong consistency (financial ledger, inventory) and which tolerate eventual consistency (feed, recommendations, notifications).

8. Evaluate & iterate

   Verbally score your own design: "The main weakness here is the fan-out write cost for high-follower accounts — I'd explore a hybrid push/pull strategy to address that." This signals self-awareness and production readiness. Ask the interviewer: "Does this look right for the scale you had in mind?" Iteration is expected and earns points. A candidate who asks for feedback is collaborating, not just performing.

Quick-reference tables

HTTP methods — safe & idempotent

* PATCH is not required to be idempotent by RFC 9110, though implementations often make it so.

HTTP status-code families

Which API style — REST vs GraphQL vs gRPC

Cross-cutting concerns checklist

Method as a flow

Patterns worth memorising

Async with polling

# Step 1: accept the work
POST /v1/exports
  ← 202 Accepted
  { "job_id": "job_77", "status_url": "/v1/exports/job_77" }

# Step 2: client polls until done
GET /v1/exports/job_77
  ← 200 { "status": "processing", "progress_pct": 62 }
  ← 200 { "status": "complete", "download_url": "..." }

Idempotent POST with Idempotency-Key

POST /v1/payments
Idempotency-Key: a3f9c2d1-…
Content-Type: application/json

{ "amount": 9900, "currency": "usd" }

# First call → executes charge → 201 Created
# Second call with same key → 200 OK (cached response, no double charge)

Cursor-based pagination response envelope

GET /v1/orders?limit=20&cursor=eyJpZCI6MjMwfQ

200 OK
{
  "data": [ /* 20 orders */ ],
  "next_cursor": "eyJpZCI6MjEwfQ",    // null if last page
  "has_more": true,
  "total_estimate": 3842                 // approximate
}

Structured error body

422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed.",
    "details": [
      { "field": "amount", "reason": "must be a positive integer" }
    ],
    "request_id": "req_9kx2m"
  }
}

Sources & further reading

• Roy Fielding — Architectural Styles and the Design of Network-based Software Architectures (REST constraints, original dissertation)
• MDN — HTTP response status codes
• MDN — HTTP request methods (safe / idempotent definitions)
• RFC 9110 — HTTP Semantics (authoritative method definitions)
• Stripe — Idempotent requests (production example of Idempotency-Key)
• Google SRE Book — Service Level Objectives
• OWASP API Security Top 10 — BOLA
• AWS — Exponential Backoff and Jitter
• OpenAPI Specification