Skip to content

API Design

What you’ll learn. How to design network APIs that are easy to use and hard to break: the principles behind REST (and its pragmatic form), when gRPC or GraphQL fit better, how to evolve an API without breaking clients, how idempotency keys make retries safe, why cursor pagination beats offset, how to model errors, and how OpenAPI contracts support tooling. Examples are Python (FastAPI-style) or TypeScript, labelled.

Once other people depend on an interface, it is nearly impossible to change freely. APIs are the hardest-to-change part of most systems (Architecture Styles). Three principles recur:

  1. Design for the consumer: start from use cases, not from your database tables.
  2. Be conservative in what you send, liberal in what you accept (Postel’s law), with caution: tolerance can freeze bad behavior in place. Prefer tolerant readers (ignore unknown fields) paired with strict, documented writers.
  3. Make the easy path the correct path: consistent naming, predictable behavior, safe defaults.

Also remember the network is not a function call: it has latency, partial failure and retries (Distributed Systems). Good APIs acknowledge that.

REST (Roy Fielding’s 2000 dissertation) is an architectural style for networked hypermedia systems. Its constraints: client-server, stateless requests, cacheability, uniform interface, layered system, and (optionally) code on demand. “REST APIs” in industry usually mean resource-oriented HTTP+JSON APIs, often without the hypermedia constraint (HATEOAS), sometimes called “Level 2” on the Richardson maturity model (resources + HTTP verbs; Level 3 adds hypermedia links).

Model nouns, not verbs. Collections are plural; identifiers are in the path.

GET /orders list orders
POST /orders create an order
GET /orders/42 read
PUT /orders/42 replace
PATCH /orders/42 partial update
DELETE /orders/42 delete
GET /orders/42/items sub-collection
POST /orders/42/cancel action that doesn't fit CRUD (acceptable, be pragmatic)
Method Safe (no side effects) Idempotent Typical use
GET yes yes read
HEAD / OPTIONS yes yes metadata
PUT no yes replace whole resource
DELETE no yes remove
PATCH no not guaranteed partial update
POST no no create / actions

Use status codes meaningfully: 200 OK, 201 Created (with Location), 202 Accepted (async work), 204 No Content, 400 (malformed), 401 (unauthenticated), 403 (forbidden), 404, 409 Conflict, 412 Precondition Failed, 422 Unprocessable Content (validation), 429 Too Many Requests (with Retry-After), 5xx for server faults. Use HTTP caching headers (ETag, Cache-Control) and conditional requests (If-None-Match, If-Match for optimistic concurrency).

# Python (FastAPI): a minimal resource with proper status codes
from fastapi import FastAPI, HTTPException, Response
from pydantic import BaseModel
app = FastAPI()
db: dict[int, dict] = {}
class OrderIn(BaseModel):
sku: str
qty: int
@app.post("/orders", status_code=201)
def create(o: OrderIn, response: Response):
oid = len(db) + 1
db[oid] = {"id": oid, **o.model_dump()}
response.headers["Location"] = f"/orders/{oid}"
return db[oid]
@app.get("/orders/{oid}")
def read(oid: int):
if oid not in db:
raise HTTPException(404, "order not found")
return db[oid]

REST strengths: ubiquitous tooling, cacheable by CDNs and browsers, human-debuggable, simple. Weaknesses: over-fetching and under-fetching (multiple round trips for a screen), no built-in schema (solved by OpenAPI), verb-oriented operations are awkward.

gRPC (Google, open-sourced 2015) is a high-performance RPC framework using HTTP/2 and Protocol Buffers (a binary, schema-first serialization). You define services and messages in .proto files and generate typed client/server code in many languages.

syntax = "proto3";
service OrderService {
rpc GetOrder (GetOrderRequest) returns (Order);
rpc WatchOrders (WatchRequest) returns (stream Order); // server streaming
}
message GetOrderRequest { string id = 1; }
message Order { string id = 1; string sku = 2; int32 qty = 3; }

Strengths: compact binary payloads, strong typing and codegen, four call styles (unary, server streaming, client streaming, bidirectional), deadlines and cancellation propagated across calls, multiplexing on one connection. Weaknesses: poor browser support without a proxy (gRPC-Web or Connect), harder to debug by hand, load balancing needs care (long-lived HTTP/2 connections stick to one backend, so use L7 or client-side balancing), less cache-friendly. Typical fit: internal service-to-service traffic, mobile clients, streaming, polyglot systems.

Protobuf evolution rules (they matter more than the syntax): never reuse or renumber field tags; add new fields with new numbers; deleted fields should be reserved; old readers ignore unknown fields. Renaming a field is safe on the wire (numbers matter, not names) but may break JSON mapping.

GraphQL (Facebook, open-sourced 2015) exposes a typed schema and lets clients specify exactly the fields they want in a single request.

type Query { order(id: ID!): Order }
type Order { id: ID! items: [Item!]! customer: Customer! }
query { order(id: "42") { id items { sku qty } customer { name } } }

Strengths: no over/under-fetching, one round trip for complex screens, strongly typed introspectable schema, good for diverse clients (web, mobile) and as a Backend-for-Frontend aggregation layer. Weaknesses and traps:

  • N+1 resolver problem: naive resolvers fetch each child separately; solve with batching (DataLoader).
  • Caching is harder: everything is a POST /graphql; HTTP/CDN caching is lost unless using persisted queries.
  • Unbounded query cost: clients can request deeply nested or enormous queries; you need depth limits, complexity analysis, timeouts and persisted-query allowlists.
  • Authorization must be applied per field/resolver, not just per endpoint.
  • Error semantics: responses are usually 200 with an errors array alongside partial data.
  • Versioning is by schema evolution (additive changes, @deprecated), which works well.
// TypeScript: DataLoader batching removes N+1
import DataLoader from "dataloader";
const customerLoader = new DataLoader<string, Customer>(async (ids) => {
const rows = await db.customers.findMany({ where: { id: { in: [...ids] } } });
const byId = new Map(rows.map(r => [r.id, r]));
return ids.map(id => byId.get(id)!); // must return in the same order as ids
});
REST/JSON gRPC GraphQL
Best for Public APIs, CRUD Internal RPC, streaming Client-driven data aggregation
Payload Text JSON Binary protobuf JSON
Schema OpenAPI (external) .proto (intrinsic) SDL (intrinsic)
Caching Excellent (HTTP) Manual Hard
Browser Native Needs proxy Native
Learning curve Low Medium Medium-high

A common architecture: gRPC between internal services, REST or GraphQL at the edge. Alternatives worth knowing: tRPC (TypeScript end-to-end types), JSON-RPC, WebSockets/Server-Sent Events for push, and async messaging (Architecture Styles).

Prefer evolving without versions: make changes that are backward compatible so old clients keep working.

  • Safe (additive): adding optional request fields, adding response fields, adding endpoints, adding enum values if clients tolerate unknowns.
  • Breaking: removing or renaming fields/endpoints, changing types or semantics, making optional fields required, tightening validation, changing error shapes, changing defaults.

When a breaking change is unavoidable, version explicitly. Options: URL path (/v2/orders, most visible and cache-friendly), header or media type (Accept: application/vnd.example.v2+json, cleaner URLs, harder to test in a browser), or date-based versions pinned per account (used by Stripe: you opt in to new behavior, the platform maintains compatibility layers). Practices: support at most a couple of versions, publish a deprecation policy, emit Deprecation/Sunset headers, track usage per version/client so you know who will break, and use consumer-driven contract tests (Testing & Code Quality).

The expand-and-contract (parallel change) pattern applies: add the new thing, migrate consumers, then remove the old.

Networks fail ambiguously: a client sends POST /payments, the connection times out, and it cannot know whether the payment happened. Retrying risks double-charging; not retrying risks losing the payment. The solution is making operations idempotent: repeating the request has the same effect as doing it once.

GET, PUT and DELETE are idempotent by definition. POST is not; the standard remedy is an idempotency key: the client generates a unique key (UUID) per logical operation and sends it in a header (Idempotency-Key; an IETF draft standardizes this). The server stores the key with the result and returns the stored result for repeats.

# Python: idempotency-key handling (sketch; use a DB unique constraint in production)
import hashlib, json
results: dict[str, tuple[str, dict]] = {} # key -> (request fingerprint, response)
def create_payment(key: str, body: dict) -> dict:
fp = hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()
if key in results:
saved_fp, saved_resp = results[key]
if saved_fp != fp:
raise ValueError("422: idempotency key reused with different payload")
return saved_resp # replay, no second charge
resp = charge_card(body) # side effect happens once
results[key] = (fp, resp)
return resp

Details that bite: the check-then-act sequence must be atomic (use a unique index and INSERT ... ON CONFLICT); concurrent duplicates should wait or return 409; keys need an expiry window (e.g. 24 hours); store the response so a retry gets the same answer; the side effect and the key record should commit in the same transaction or the operation itself must be naturally idempotent (PUT /orders/42/status = shipped). See Distributed Systems for why exactly-once delivery is really at-least-once plus idempotence.

Never return unbounded lists. Three approaches:

  • Offset/limit (?limit=20&offset=40): simple, supports “jump to page N”. Problems: cost grows with offset (OFFSET 1000000 scans and discards a million rows) and results shift if rows are inserted/deleted between requests (duplicates or skips).
  • Cursor/keyset pagination (?limit=20&after=eyJpZCI6...): the cursor encodes the last seen sort key; the query is WHERE (created_at, id) < (:ts, :id) ORDER BY created_at DESC, id DESC LIMIT 20, which uses an index and runs in time independent of depth. Stable under concurrent writes. Cannot jump to page N. Cursors should be opaque (base64 of structured data, ideally signed) so you can change the encoding.
  • Page-token APIs (Google AIP-158 style): page_size + page_token, response includes next_page_token.
# Python: keyset pagination query shape (SQL) with opaque cursor
import base64, json
def encode_cursor(ts: str, id_: int) -> str:
return base64.urlsafe_b64encode(json.dumps([ts, id_]).encode()).decode()
SQL = """
SELECT id, created_at, title FROM posts
WHERE (created_at, id) < (%s, %s)
ORDER BY created_at DESC, id DESC
LIMIT %s
""" # fetch limit+1 rows to know whether there is a next page

Always include a unique tiebreaker in the sort (id), otherwise rows with equal sort keys vanish between pages. Return next cursors and optionally has_more; avoid total counts on huge tables (counting is expensive).

Errors are part of the contract. Make them machine-readable, consistent and safe.

RFC 9457 “Problem Details for HTTP APIs” (successor to RFC 7807) standardizes a JSON shape with media type application/problem+json:

{
"type": "https://api.example.com/problems/insufficient-funds",
"title": "Insufficient funds",
"status": 422,
"detail": "Balance 30.00 is less than required 50.00.",
"instance": "/payments/abc123",
"errors": [{ "field": "amount", "code": "exceeds_balance" }]
}

Guidelines: stable machine-readable code/type (clients switch on this, not on message text); human message for developers; per-field validation errors; correlation/request ID for support; never leak stack traces, SQL or internals; distinguish client errors (4xx, do not retry unchanged) from server errors (5xx, maybe retry); advertise retryability (Retry-After, 429). gRPC has a canonical status-code set (NOT_FOUND, INVALID_ARGUMENT, DEADLINE_EXCEEDED, UNAVAILABLE, …) plus rich error details; GraphQL carries errors in the body alongside partial data.

OpenAPI (formerly Swagger; current line is 3.x) is a language-agnostic description format (YAML/JSON) for HTTP APIs: paths, parameters, schemas, responses, auth. It enables docs (Swagger UI, Redoc), client/server codegen, mock servers, validation, linting (Spectral) and contract tests.

openapi: 3.1.0
info: { title: Orders API, version: "1.0.0" }
paths:
/orders/{id}:
get:
operationId: getOrder
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
responses:
"200":
description: The order
content:
application/json:
schema: { $ref: "#/components/schemas/Order" }
"404":
description: Not found
content:
application/problem+json:
schema: { $ref: "#/components/schemas/Problem" }
components:
schemas:
Order:
type: object
required: [id, sku, qty]
properties:
id: { type: string }
sku: { type: string }
qty: { type: integer, minimum: 1 }

Design-first vs code-first. Design-first: write the spec, review it, generate stubs; it makes API design a reviewable artifact before implementation. Code-first: annotate the code (FastAPI, NestJS) and generate the spec; less drift, but the API design becomes a side effect. Either way, detect breaking changes in CI by diffing specs (tools such as oasdiff do this). Related contract tools: Protobuf plus buf breaking, GraphQL schema checks, and consumer-driven contracts (Pact).

  • Authentication: OAuth 2.0/OIDC bearer tokens or API keys; see Reliability & Security.
  • Rate limiting and quotas: expose via 429 and RateLimit headers (case study).
  • Filtering/sorting: whitelisted fields; consistent query parameter syntax.
  • Bulk operations and partial failure semantics (207 Multi-Status or per-item results).
  • Long-running operations: return 202 plus an operation resource to poll, or use webhooks (sign and retry them, and make receivers idempotent).
  • Time: ISO 8601/RFC 3339 in UTC; money as integer minor units plus currency, never floats.
  • An API is a long-lived contract; design for consumers and for evolution.
  • REST gives cacheability and ubiquity; gRPC gives typed, efficient internal RPC and streaming; GraphQL gives client-shaped queries at the cost of caching and complexity control.
  • Prefer additive, backward-compatible change; version explicitly only when necessary.
  • Idempotency keys make retries safe for non-idempotent operations; implement atomically.
  • Keyset (cursor) pagination scales and is stable; offset pagination does not.
  • Standardize errors (RFC 9457), with stable machine codes.
  • OpenAPI/protobuf/GraphQL schemas are machine-checkable contracts: use them in CI.
  1. Conceptual. Classify as breaking or non-breaking: (a) add an optional response field, (b) rename qty to quantity, (c) add a value to an enum returned to clients, (d) make an optional request field required, (e) tighten max length from 255 to 100.
  2. Hands-on (Python). Implement idempotency-key middleware backed by SQLite using INSERT with a unique constraint. What happens with two concurrent requests with the same key?
  3. Hands-on (SQL/Python). Convert an offset-paginated GET /posts into keyset pagination ordered by (created_at DESC, id DESC); write the index required.
  4. Conceptual. A mobile team complains the order screen needs four REST calls. Compare adding a GraphQL layer, a BFF endpoint, and compound documents.
  5. Hands-on. Write an OpenAPI fragment for POST /orders with a 201 response including Location and a 422 problem-details response.
Solutions (sketch)
  1. (a) non-breaking; (b) breaking; (c) potentially breaking for strict clients (document that enums are open); (d) breaking; (e) breaking for existing writers.
  2. Primary key on key; the second insert fails; either wait for the first to finish and return its stored result, or return 409 and let the client retry.
  3. CREATE INDEX posts_created_id ON posts (created_at DESC, id DESC); then use the tuple comparison query shown above.
  4. GraphQL: flexible but adds a new stack and caching/cost issues. BFF: one tailored endpoint per screen; simple and cacheable but couples server to screens. Compound documents or ?include=/field selection: moderate flexibility with REST.
  5. Under responses: "201": { description: Created, headers: { Location: { schema: { type: string } } } } and "422": { content: { application/problem+json: {...} } }.
  • Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures (doctoral dissertation, 2000), chapter 5.
  • RFC 9110 (HTTP Semantics) and RFC 9457 (Problem Details for HTTP APIs).
  • Google, API Improvement Proposals (AIPs, google.aip.dev), a thorough design guide.
  • Arnaud Lauret, The Design of Web APIs (2nd ed., 2024).
  • OpenAPI Specification documentation (spec.openapis.org) and gRPC and Protocol Buffers documentation (grpc.io, protobuf.dev).
  • GraphQL specification and best-practices docs (graphql.org).
  • Brandur Leach, “Implementing Stripe-like Idempotency Keys in Postgres” (blog post, 2017).