API Design in System Design: REST, Versioning, Pagination & Idempotency (Visualized)

API design is the practice of defining the contract between a service and its clients — the resources it exposes, the operations allowed on them, the shape of requests and responses, and the rules for how that contract evolves over time. A well-designed API is predictable, hard to misuse, and stable enough that clients written today still work next year.

Most public APIs you have used — Stripe, GitHub, Twilio — succeed less because of clever code and more because of disciplined design: consistent naming, correct use of HTTP, careful versioning, and clear error semantics. This guide walks through those decisions in the order you actually make them when designing a service.

In a REST API, you model your domain as resources — nouns like users, orders, or invoices — and act on them with HTTP methods. The golden rules: use plural nouns for collections (/users), put the identifier in the path (/users/42), nest only to express ownership (/users/42/orders), and keep verbs out of URLs. POST /users creates a user; you never need /createUser.

The HTTP method carries the verb, and each one comes with a contract the whole web relies on. GET is safe (no side effects) and cacheable; PUT and DELETE are idempotent (repeating them has the same effect as doing them once); POST is neither. Respecting these semantics is what lets proxies, browsers, and clients reason about your API.

The request/response cycle is the heartbeat of any API: the client sends a method and path, the server does work, and a status code communicates the outcome — 2xx success, 4xx the client's fault, 5xx the server's fault. The animation below traces that round trip.

Once external clients depend on your API, you can never break the contract without warning. Versioning lets you ship incompatible changes while old clients keep working. The most common approach is a version prefix in the URL (/v1/users, /v2/users); alternatives include a custom header or an Accept media type. Stripe takes a notable approach: a single date-based version pinned per account, so existing integrations are frozen in time while new ones opt into the latest behavior.

The router below shows how a gateway dispatches the same logical request to different backend implementations based on its version — old traffic to v1, new traffic to v2 — so both can run side by side during a migration.

No endpoint should return an unbounded list. Pagination breaks large result sets into pages. Offset pagination (?limit=20&offset=40) is simple but slow on deep pages and unstable when rows are inserted mid-scroll. Cursor pagination instead returns an opaque pointer to the last item seen (?after=eyJpZCI6MTAwfQ); the next request resumes exactly there. It is stable under concurrent writes and stays fast at any depth, which is why Stripe and the GitHub API use it for large collections.

Networks fail mid-request, so clients retry — but retrying a POST /charges could bill a customer twice. Idempotency guarantees that making the same request many times has the same effect as making it once. The standard pattern, popularized by Stripe, is an idempotency key: the client generates a unique key per logical operation and sends it as a header. The server stores the result against that key, so a retry with the same key returns the original response instead of re-executing the action.

Errors are part of your API contract, so design them deliberately. Use the right status code (400 bad input, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation, 429 rate limited), and return a consistent machine-readable body with a stable code, a human message, and ideally a field pointer. A predictable error shape lets clients branch on code rather than parsing prose.

Authentication proves who the caller is; authorization decides what they may do. Server-to-server APIs commonly use API keys or OAuth2 client credentials; user-facing APIs use OAuth2 with short-lived bearer tokens (often JWTs) refreshed by a long-lived token. Always send credentials over TLS in the Authorization header — never in the URL, where they leak into logs and browser history. Scope tokens narrowly so a leaked key for reading invoices cannot also delete them.

Rate limiting protects your service from abuse and noisy neighbors by capping how many requests a client may make in a window — typically with a token-bucket algorithm. Communicate limits in headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and return 429 Too Many Requests with a Retry-After header when a client exceeds them, so well-behaved clients can back off gracefully rather than hammering you.

REST is the default for public, resource-oriented HTTP APIs (Stripe, GitHub). gRPC — an RPC style over HTTP/2 with Protobuf — wins for high-throughput internal service-to-service traffic where latency and strong contracts matter. GraphQL lets clients request exactly the fields they need in one round trip, eliminating over- and under-fetching, which shines for rich frontends with many entities (used by the GitHub v4 API). None is universally best; the right choice depends on who consumes the API and how.

A RESTful API models the domain as resources identified by URLs, manipulates them with standard HTTP methods that respect safe/idempotent semantics, is stateless (each request carries its own context), and uses status codes and media types as the web intends. The aim is a uniform, predictable interface that any HTTP client can consume without bespoke logic.

Version when you must make a breaking change — removing a field, changing a type, or altering behavior clients rely on. Additive changes (new optional fields, new endpoints) usually do not need a new version. URL prefixes like /v1 are the simplest and most visible; header or media-type versioning keeps URLs clean; Stripe's date-pinned versions freeze each integration in place. Whatever you pick, document a deprecation policy.

Offset pagination gets slow on deep pages because the database must scan and discard every skipped row, and it can show duplicates or gaps when rows are inserted or deleted mid-scroll. Cursor pagination resumes from an opaque pointer to the last item seen, so it stays fast at any depth and remains stable under concurrent writes. That is why large public APIs like Stripe and GitHub default to it.