#API design

The framework gives API design five minutes in phase 3. This page is what to say inside those five minutes, and what to say when the interviewer decides the API is the deep dive.

#1 · REST, GraphQL, gRPC

#How to actually choose

Public API → REST. Internal service-to-service → gRPC. A client with wildly varying data needs, especially mobile → GraphQL.

REST for anything public, and the reason is caching and familiarity: HTTP caching, CDNs, proxies and every debugging tool on earth already understand it. A public GraphQL API means every consumer must learn your schema and you lose edge caching.

gRPC internally, where you control both ends: binary payloads, HTTP/2 multiplexing, generated clients, and a schema that breaks the build rather than production when it changes. The browser problem does not apply between your own services.

GraphQL when the client's needs vary and round trips are expensive. The canonical case is a mobile app that would otherwise make six REST calls to render one screen.

GraphQL's real costs — name them, because they are what the follow-up probes:

#2 · REST done properly

GET    /v1/users/{id}                 -> 200 the user
GET    /v1/users/{id}/posts?limit=20  -> 200 a page
POST   /v1/posts                      -> 201 + Location header
PATCH  /v1/posts/{id}                 -> 200 partial update
DELETE /v1/posts/{id}                 -> 204 no content

Status codes that carry information:

401 versus 403 is a small thing that gets noticed. And returning 404 instead of 403 for resources the caller may not know about is a deliberate information-leak defence worth mentioning.

#3 · Pagination

Cursor, not offset, and be able to say why:

OFFSET:  GET /posts?page=3&limit=20
  - the database SKIPS 40 rows to return 20 -- cost grows with page number
  - a row inserted at the head SHIFTS everything: the reader sees an item
    twice, or misses one entirely
  - deep pages get slower and slower

CURSOR:  GET /posts?after=eyJ0IjoxNzAwfQ&limit=20
  - WHERE (created_at, id) < (cursor) ORDER BY ... LIMIT 20
  - uses the index directly; page 1000 costs the same as page 1
  - stable under concurrent inserts

Encode the cursor opaquely — base64 of (sort_key, id) — so clients cannot construct one and you can change the scheme later. Include the tiebreaker id, or rows sharing a timestamp are skipped or repeated.

The honest trade-off: cursors cannot jump to page 50. If the product needs numbered pages, you need offset — so cap the depth, and say so.

#4 · Versioning

The best versioning strategy is not needing one. Adding a field is backward-compatible; removing or renaming one is not. If every change is additive and clients ignore unknown fields, you may never cut v2. Version when you must break something — and then run both for a deprecation window with usage metrics telling you when the old one is safe to retire.

#5 · Webhooks

The server calls you when something happens — the inverse of polling.

sequenceDiagram
    participant P as Provider
    participant Q as Their queue
    participant Y as Your endpoint
    P->>Q: event occurs
    Q->>Y: POST /webhooks/x (signed)
    Y-->>Q: 200 immediately
    Y->>Y: enqueue, process async
    Note over Q,Y: no 2xx -> retry with backoff -> DLQ

Five things a webhook receiver must do, and they map exactly onto idempotency:

Webhooks versus polling versus streaming:

#6 · The API gateway

One entry point in front of many services.

The anti-pattern: business logic in the gateway. It becomes a shared component every team must change and no team owns — a distributed monolith with extra latency. Keep it to cross-cutting concerns.

BFF (backend-for-frontend) is worth naming: one gateway per client type — web, iOS, Android — each shaping responses for that client's needs. It solves the same over-fetching problem GraphQL does, without adopting GraphQL.

#7 · What to say in the round

"REST over HTTP for the public API — it caches at the edge for free and every client already understands it. Cursor pagination rather than offset, because offset re-scans and shifts under concurrent inserts. Internal service calls are gRPC: binary, multiplexed, and the schema breaks the build instead of production.

Version in the path, but I'd aim never to cut v2 — additive changes with clients ignoring unknown fields. Writes carry an idempotency key so a client retry after a timeout cannot double-charge, and the gateway handles TLS, auth and rate limiting so no service re-implements them."

#8 · Interview questions

#Stop condition

You know this block when you can:

1. choose between REST, GraphQL and gRPC on caching, control and payload grounds,
2. explain the N+1 problem and name the batching fix,
3. give both reasons offset pagination fails,
4. argue that the best versioning is additive change,
5. list the five requirements of a webhook receiver, and
6. say what must not go in a gateway.