API Design — REST, RPC, GraphQL

An API is a contract between services. Three dominant styles:

**REST** (Representational State Transfer): resource-oriented over HTTP. GET /users/42 (read), POST /users (create), PUT /users/42 (replace), PATCH /users/42 (partial update), DELETE /users/42. Verbs = HTTP methods; nouns = URLs. Easy to understand, works with any HTTP client, cacheable. The web standard.

**RPC** (Remote Procedure Call): you call a function that happens to run on another machine. gRPC (Google's high-performance RPC with Protobuf serialization) is the modern example. Fast, strongly typed, bidirectional streaming. Great for internal service-to-service. Less browser-friendly (needs special client code).

**GraphQL**: the client writes a query specifying exactly which fields it wants; the server returns exactly that. Solves over-fetch (REST often returns too much) and under-fetch (N+1 requests for related data). Added complexity on the server (resolvers, N+1 risk), caching harder than REST.

HTTP status codes that matter: 2xx success, 3xx redirect, 4xx client error (400 bad request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 422 unprocessable), 5xx server error (500 internal, 502 bad gateway, 503 unavailable, 504 timeout). Learn these — they compose the language your consumers read.

**Key design principles**: **versioning** (URL path /v1/ or header — commit to compatibility within a version), **pagination** (never unbounded lists — limit + cursor or offset), **idempotency** (safe to retry; PUT/DELETE naturally, POST needs idempotency-key header), **error format** (consistent shape: `{ error: { code, message, details } }`).