API Design

An API is a promise. The design work is deciding what you are promising and how you will change it later without breaking callers.

Style. REST models resources with HTTP verbs and gets caching, status codes, and tooling for free. GraphQL lets clients ask for exactly the fields they need, which solves over-fetching for varied clients and moves complexity into query cost control. gRPC is compact and fast, and it is best suited to service-to-service calls rather than public browser-facing APIs.

Idempotency. GET, PUT, and DELETE are idempotent by definition; POST is not. For operations that must not double-apply — payments especially — accept a client-supplied idempotency key and return the original result on retry. Without it, a timeout leaves the client unable to retry safely, because it cannot tell whether the request landed.

Pagination. Offset pagination (?page=3) is simple and drifts: rows inserted during traversal cause skipped or repeated results, and deep offsets get slow. Cursor pagination encodes the last-seen sorted key and stays correct and fast at any depth.

Versioning and evolution. Adding a field is safe; removing one, renaming one, or narrowing an accepted value is not. Prefer additive change, and treat any client relying on undocumented behaviour as a client you will still break. When you must version, do it explicitly and keep the old version alive long enough for callers to migrate.

Errors should be machine-readable: a stable code the client can branch on, plus a human message. Never make callers parse prose.