API design: REST done well, and when to reach for something else

01First principles: what is an API contract?

An API is a promise about behavior between two systems that deploy independently. Everything in good API design follows from that one fact:

02REST done well

Resources, not actions

REST models your domain as nouns (resources) manipulated by a small fixed set of verbs (HTTP methods).

GET    /incidents
GET    /incidents/42
POST   /incidents
PATCH  /incidents/42
DELETE /incidents/42

GET  /getIncidents
POST /incident/fetch
POST /createNewIncident
POST /incidents/42/update
GET  /deleteIncident?id=42  ← never mutate on GET

Why? Uniformity. If everything is verb + noun, a new consumer can guess 80% of your API. Caches, proxies, and browsers also rely on verb semantics (GET is cacheable and safe; DELETE is not).

Sub-resources express ownership: GET /incidents/42/comments. Don't nest more than ~2 levels — /orgs/1/repos/2/issues/3/comments/4 is misery; give comments their own top-level ID.

Actions that don't map to CRUD are fine as sub-resource verbs when honest nouns don't exist:

POST /incidents/42/resolve        # state transition
POST /pull-requests/42/approve    # Sentinel's approval gate is exactly this shape

Purists say model it as PATCH {"status": "resolved"}. Either is defensible in an interview — say you'd pick one convention and be consistent.

The verbs, precisely

Idempotent = calling it N times has the same effect as once. This matters because retries are inevitable. PUT /users/42 with the same body twice → same end state. POST /payments twice → two charges. That's why POST needs idempotency keys (section 07).

03Status codes — the ones that matter

You don't need all 60. You need these, used honestly:

04Error format — pick one shape, everywhere

{
  "error": {
    "type": "validation_error",
    "message": "end_date must be after start_date",
    "field": "end_date",
    "request_id": "req_8fa2c1"
  }
}

• A machine-readable type (stable, documented) so clients can branch on it.
• A human message for logs and debugging.
• A request_id you also log server-side — turns "it failed" support tickets into a one-grep investigation. The single highest-leverage field.
• RFC 9457 ("Problem Details", application/problem+json) is the standardized version of this — worth name-dropping.

05Pagination, filtering, field selection

Never return unbounded lists. Two schools:

{ "data": [...], "next_cursor": "eyJ...", "has_more": true }

Filtering, sorting, field selection

GET /incidents?status=open&severity=high&sort=-created_at&fields=id,title,status

• Query params for filters; - prefix (or sort=created_at:desc) for direction.
• Reject unknown filter params loudly (400) rather than silently ignoring — silent ignoring means a typo'd filter returns everything, which has caused real incidents (imagine ?user_id misspelled on a DELETE-adjacent list).
• Field selection (fields=) is a lightweight answer to over-fetching before you reach for GraphQL.

06Versioning

You version because you promised not to break callers. Options:

07Idempotency keys — the retry-safety mechanism

Problem: client POSTs "create payment", the network drops before the response arrives. Did it succeed? The client's only sane move is retry — but naive retry double-charges.

Subtleties worth volunteering

• The key must be inserted with a unique constraint / atomic SET NX, or two racing requests both think they're first.
• Store the response and status code — the retry should be indistinguishable from the original.
• Same key, different body? That's a client bug → 422.
• This is exactly why GitHub webhook deliveries carry a delivery ID: Sentinel dedupes webhook redeliveries the same way — GitHub retries deliveries, and an issue-detection pipeline that fires twice per event creates duplicate fix PRs. Concrete production story; use it.

08Authentication and authorization

API keys

A random secret in a header (Authorization: Bearer sk_live_... or X-Api-Key).

• Best for: server-to-server, one org per key, machine callers.
• Store only a hash of the key server-side (they're passwords). Show a prefix (sk_live_a1b2...) for identification.
• Support rotation: allow two active keys per client so they can roll without downtime.
• Weakness: no user identity, no scoping by default, long-lived → damage if leaked. Mitigate with scopes and per-key rate limits.

OAuth2 — the intuition, not the RFC

OAuth2 solves delegation: "let app A act on user U's data at service B, without U giving A their password." Mental model: the user is escorted to the service they trust (GitHub), says "yes, this app may read my repos", and the app receives a scoped, revocable access token instead of credentials.

JWT — structure and pitfalls

A JWT is three base64url segments: header.payload.signature.

header    {"alg": "RS256", "typ": "JWT", "kid": "key-2026-01"}
payload   {"sub": "user_42", "iss": "auth.myco.com", "aud": "api.myco.com",
           "exp": 1767225600, "iat": 1767222000, "scope": "incidents:read"}
signature = sign(base64(header) + "." + base64(payload), key)

The point: the server can verify the token without a DB lookup — the signature proves the issuer minted it and nothing was altered. That's the whole value: stateless auth that scales horizontally.

Authorization models, briefly

• RBAC — roles → permissions (admin, member, viewer). Right default for most products.
• Scopes — per-token capability narrowing (repo:read), orthogonal to roles.
• Resource-level checks — "is this their incident?" Must be enforced in the handler/query, not just middleware — missing this is BOLA/IDOR, the #1 API vulnerability class (OWASP API Top 10). Test: user A requests /incidents/{B's id} → must be 404/403.

09Rate limiting

Protects you from abuse, bugs (retry storms), and noisy neighbors. Algorithms in one line each:

Headers (tell clients how to behave):

RateLimit-Limit: 100
RateLimit-Remaining: 12
RateLimit-Reset: 1767225600        # or seconds-until-reset
Retry-After: 30                    # on the 429 itself

Older convention: X-RateLimit-* — GitHub uses these; the IETF draft standardizes the unprefixed forms. Knowing both reads well.

10Webhooks — designing the other direction

You're unusually strong here: Sentinel is a webhook consumer at its front door. Talk about both sides. A webhook = the server calls you on events, instead of you polling.

Signing (authenticity)

Anyone who finds your webhook URL can POST fake events. Fix: provider computes HMAC-SHA256(secret, raw_body) and sends it in a header (GitHub: X-Hub-Signature-256: sha256=...). Consumer recomputes and compares with a constant-time comparison.

@app.post("/webhook")
def handle(payload: dict):
    # anyone can POST fake events
    # == compare leaks timing info
    # parsed JSON won't re-serialize
    #   byte-identically anyway
    process(payload)   # slow, inline
    return {"ok": True}

@app.post("/webhook")
def handle(req):
    raw = req.body            # raw bytes!
    mac = hmac.new(SECRET, raw,
                   sha256).hexdigest()
    if not hmac.compare_digest(
        "sha256="+mac, req.headers[
        "X-Hub-Signature-256"]):
        return 401     # reject FIRST
    queue.put(raw)            # async
    return 200         # fast ack

Gotchas that show real experience:

• Sign/verify the raw bytes, before JSON parsing — re-serialized JSON won't match (key order, whitespace).
• Use hmac.compare_digest, never == — timing attacks.
• Include a timestamp in the signed material and reject old deliveries (replay protection — Stripe does this, ±5 min tolerance).
• Rejecting unsigned/bad-signature requests should be the first thing the handler does.

Retries and delivery semantics

Consumers are flaky, so providers retry — which means delivery is at-least-once, never exactly-once. Consequences for both sides:

As the provider: retry with exponential backoff (e.g. 1m, 5m, 30m, 2h... over ~24h); treat non-2xx or timeout (>10s) as failure; give each event a stable delivery/event ID; provide a dead-letter view + manual redelivery in the dashboard; disable endpoints that fail for days (and notify).

As the consumer (your production reality):

1. Return 200 fast, process async. Validate signature → enqueue → 200. Never do slow work (an LLM call!) inline, or the provider times out and retries, and now you have duplicates and pressure.
2. Dedupe by event ID — idempotent consumption (store processed IDs with a TTL).
3. Don't assume ordering. Retries and parallel delivery reorder events; use the event's payload/timestamps or re-fetch current state from the API rather than trusting arrival order.
4. Fetch, don't trust: for critical actions, treat the webhook as a hint and confirm state via the API ("webhook says PR merged" → GET the PR).

11When not REST: GraphQL and gRPC

Don't be a zealot; be a chooser of tradeoffs.

GraphQL — when the client's data needs vary a lot

• Problem it solves: over-fetching / under-fetching / N+1 round-trips for UI clients. One request describes exactly the shape needed; great when many differently-shaped frontends (web, iOS, partner apps) share one backend, or a screen aggregates 5 resources.
• Costs: caching gets harder (everything is POST /graphql — no HTTP-level cache semantics); you must defend against expensive queries (depth/complexity limits, persisted queries); N+1 moves into your resolvers (dataloader pattern); authorization becomes per-field, which is easy to get wrong; it's an extra layer of infra.
• Verdict to give: GraphQL for a client-facing aggregation layer with diverse UIs; REST for service-to-service and public APIs (simpler, cacheable, curl-able).

gRPC — when it's your own services talking

• What it is: RPC over HTTP/2 with Protobuf — a typed, compiled contract (.proto) generating client/server stubs in any language.
• Wins: compact binary encoding + HTTP/2 multiplexing → much lower latency/CPU than JSON; contract-first with codegen (type-safe clients for free); first-class streaming (client-, server-, and bidirectional) — natural fit for token streaming or long-lived feeds; deadlines and cancellation built in.
• Costs: not browser-native (need grpc-web or a gateway); binary payloads are not human-debuggable with curl; protobuf schema evolution has its own discipline (field numbers are forever, never reuse them).
• Verdict to give: gRPC for internal service-to-service at scale and for streaming; REST/JSON at the public edge.

12Rapid-fire interview Q&A

13Self-test