API Design for System Design: REST, Status Codes, Pagination and Versioning

An API is a promise. Once a mobile app ships that calls GET /photos/123 and expects a field called caption, you cannot rename that field without breaking every phone that has not updated. Databases can be migrated in a night; installed clients cannot. That is why the API is one of the few parts of a design that is expensive to change, and why interviewers ask you to define it before you draw the architecture.

In the seven-phase method this is phase 3, Interface. This article teaches you to design APIs that are clear, safe to retry, and able to evolve.

• What REST means in practice: resources, representations and URLs.
• Which HTTP methods are safe and idempotent, and why that matters for retries.
• Which status codes to use, and a consistent error format.
• How to validate requests at the boundary.
• Offset versus cursor pagination, and why cursors win for large lists.
• Filtering, sorting, authentication, rate-limit responses and idempotency keys.
• How to version an API without breaking clients.
• When gRPC or GraphQL is a better fit than REST.

The API defines what the system must do from the outside. Once you know the operations (create a photo, read a feed, like a photo), you know the read and write paths you must design, and their shapes tell you a lot about the data model. A good API definition in an interview takes three or four minutes and saves you from designing machinery for operations nobody needs.

There are two kinds of API in most systems:

• External APIs used by browsers, mobile apps and partners. They change slowly and must be backward compatible.
• Internal APIs between your own services. They can change faster, but still need care, because services are deployed at different times.

REST (representational state transfer) is a style for designing HTTP APIs. In practice it means:

1. Model the API as resources (nouns): users, photos, comments, orders.
2. Give each resource a URL: /photos/123.
3. Use HTTP methods for the operation: GET to read, POST to create, PUT or PATCH to update, DELETE to remove.
4. Exchange representations, usually JSON, of the resource's state.
5. Keep requests stateless: each request carries what the server needs, such as an authentication token.

Keep nesting shallow. /users/42/photos/123/comments/9 is hard to use; /comments/9 is usually enough once a comment has its own id.

Not everything maps neatly to a noun. Actions such as "cancel an order" are often modelled as a state change (PATCH /orders/77 with {"status": "cancelled"}) or as a sub-resource (POST /orders/77/cancellation). Both are fine; be consistent.

RFC 9110 defines two properties that matter a great deal in distributed systems (HTTP Semantics):

• A safe method is read-only: calling it should not change server state.
• An idempotent method can be called several times with the same effect as calling it once.

Networks fail in an annoying way: a client sends a request, and the connection drops before the response arrives. Did the server process it? The client cannot know. The safe reaction is to retry. For GET, PUT and DELETE that is harmless: reading twice, setting the same value twice, or deleting something already deleted leaves the same end state.

For POST /payments, a retry might charge the customer twice. The standard fix is an idempotency key: the client generates a unique id for the operation and sends it in a header. The server remembers the key and its result; if the same key arrives again, it returns the stored result instead of repeating the operation.

POST /paymentsIdempotency-Key: 6f1c2a9e-1b0d-4c55-9a4e-2f1a7d0c3b88Content-Type: application/json{"order_id": "ord_77", "amount": 49900, "currency": "INR"}

This pattern is widely used by payment providers. Stripe's documentation, for example, describes saving the status code and body of the first request for a key and returning the same result for retries, comparing parameters to detect misuse, and allowing keys to be pruned after at least 24 hours (Idempotent requests). The IETF has worked on standardising an Idempotency-Key request header; as of October 2026 the draft is listed as expired and is not an RFC (Idempotency-Key header draft), so treat the header name as a common convention rather than a standard.

Article 20 covers how to build this safely. For now: whenever an API creates something important or moves money, ask how a retry is made safe.

The split between 4xx and 5xx matters operationally. A 4xx means the client must change something; retrying the same request will fail again. A 5xx means the server had a problem; a retry later might succeed. Clients, load balancers and alerting all rely on this difference.

Return errors in one predictable shape so clients can handle them in one place. RFC 9457 defines a standard JSON format called "problem details" (Problem Details for HTTP APIs):

{  "type": "https://api.pixly.example/problems/caption-too-long",  "title": "Caption too long",  "status": 422,  "detail": "Captions can be at most 2,200 characters; this one has 2,512.",  "instance": "/photos"}

Never put stack traces, SQL or internal hostnames in error responses. They help attackers more than users.

Every request from outside is untrusted. Validate it as soon as it arrives, before it reaches business logic or the database:

• Shape and types: required fields present, numbers are numbers, ids match the expected format.
• Size limits: maximum body size, maximum string lengths, maximum list lengths, maximum page size. Unbounded inputs are a classic way to exhaust memory.
• Ranges and enums: quantities positive, status values from a known list, dates in a sensible range.
• Authorisation: the caller may act on this resource, not just on resources of this type. OWASP lists broken object-level authorisation as the top API security risk (article 28).

Rejecting bad input early with a clear 400 or 422 is cheaper for everyone than failing deep inside the system.

Any endpoint that returns a list needs pagination. Returning 50,000 photos in one response would be slow, memory-hungry and useless to a phone screen.

GET /users/42/photos?limit=20&offset=40

The server runs something like "skip 40 rows, return the next 20". It is easy to understand and allows jumping to page 7. It has two problems:

1. It gets slower as the offset grows. Most databases must still walk past the skipped rows. Page 5,000 of a large table can be very slow.
2. It is unstable when data changes. If a new photo is added at the top between requests, every item shifts down by one. The client sees one photo twice. If one is deleted, the client misses one.

GET /users/42/photos?limit=20-> {"items": [...], "next_cursor": "aWQ6OA"}GET /users/42/photos?limit=20&cursor=aWQ6OA

The server returns a cursor that encodes the position of the last item (for example its creation time and id). The next request asks for "items after this position", which an index can answer directly, however deep you are. New items at the top do not shift the next page.

The cursor should be opaque to clients (for example, base64-encoded), so you can change its internal format later without breaking them.

This small Java program simulates both approaches on a list of posts ordered newest first, with a new post arriving between page 1 and page 2. It is a model of the idea, not a web service; read it as pseudocode if you prefer another language.

// File: PaginationDemo.javaimport java.nio.charset.StandardCharsets;import java.util.ArrayList;import java.util.Base64;import java.util.List;public class PaginationDemo {    // Posts are identified by increasing ids; a higher id means newer. The feed shows newest first.    static List<Integer> posts = new ArrayList<>();    static List<Integer> offsetPage(int offset, int limit) {        List<Integer> page = new ArrayList<>();        for (int i = offset; i < Math.min(offset + limit, posts.size()); i++) {            page.add(posts.get(i));        }        return page;    }    // Returns the ids strictly older than the cursor position.    static List<Integer> cursorPage(String cursor, int limit) {        int after = cursor == null ? Integer.MAX_VALUE : decode(cursor);        List<Integer> page = new ArrayList<>();        for (int id : posts) {            if (id < after && page.size() < limit) {                page.add(id);            }        }        return page;    }    static String encode(int id) {        return Base64.getUrlEncoder().withoutPadding()                .encodeToString(("id:" + id).getBytes(StandardCharsets.UTF_8));    }    static int decode(String cursor) {        String raw = new String(Base64.getUrlDecoder().decode(cursor), StandardCharsets.UTF_8);        return Integer.parseInt(raw.substring(3));    }    static void reset() {        posts.clear();        for (int id = 10; id >= 1; id--) {            posts.add(id);        }    }    public static void main(String[] args) {        reset();        System.out.println("Offset page 1: " + offsetPage(0, 3));        posts.add(0, 11); // a new post arrives at the top        System.out.println("Offset page 2: " + offsetPage(3, 3) + "  <- 8 is shown twice");        reset();        List<Integer> first = cursorPage(null, 3);        String next = encode(first.get(first.size() - 1));        System.out.println("Cursor page 1: " + first + " next=" + next);        posts.add(0, 11);        List<Integer> second = cursorPage(next, 3);        System.out.println("Cursor page 2: " + second + " next=" + encode(second.get(second.size() - 1)));    }}

Offset page 1: [10, 9, 8]Offset page 2: [8, 7, 6]  <- 8 is shown twiceCursor page 1: [10, 9, 8] next=aWQ6OACursor page 2: [7, 6, 5] next=aWQ6NQ

The offset version repeats post 8 because everything shifted down. The cursor version continues exactly where it stopped. In a real database, the cursor query is a range scan on an index such as (owner_id, created_at, id), so its cost does not grow with page depth (article 13 explains why).

Always cap the page size (for example a maximum of 100) so one request cannot ask for a million rows.

• Filtering with query parameters: GET /orders?status=shipped&created_after=2026-09-01.
• Sorting with a parameter: sort=-created_at (minus for descending). Allow sorting only on fields you have indexed, or a single request can trigger a full table scan.
• Field selection (optional): fields=id,caption,thumbnail_url lets mobile clients fetch less data.

Each filter and sort option is a promise to support a query efficiently. Offer the ones clients need, not every possible combination.

These apply to almost every endpoint, so decide them once:

• Authentication. External APIs commonly use bearer tokens in the Authorization header; partner APIs often use API keys. Article 28 compares sessions, tokens and JWTs.
• Rate limits. Protect the system and share capacity fairly. Respond with 429 Too Many Requests and, when you can, a Retry-After header. Article 31 designs a rate limiter.
• Request ids. Accept or generate a request id and return it in a header, so a user's error report can be traced through logs (article 25).
• Caching headers. Cache-Control and ETag let clients and CDNs avoid refetching unchanged data (articles 09 and 10).

HTTP has a built-in way to avoid two clients overwriting each other's changes. The server returns a version tag (ETag) with a resource. A client that updates the resource sends If-Match with the tag it read. If someone else changed the resource in the meantime, the tag no longer matches and the server returns 412 Precondition Failed instead of silently overwriting. Article 14 explains this "optimistic concurrency" pattern in the database.

If an operation takes longer than a few seconds (generating a report, transcoding a video), do not hold the HTTP request open. Return 202 Accepted with a URL where the client can check the status:

POST /exports            -> 202 Accepted, Location: /exports/exp_31GET  /exports/exp_31     -> 200 {"status": "running", "progress": 40}GET  /exports/exp_31     -> 200 {"status": "done", "download_url": "..."}

Article 05 covers this asynchronous pattern and its alternatives.

APIs evolve. The goal is to change them without breaking existing clients.

Backward-compatible changes (safe to make in place):

• adding a new endpoint;
• adding an optional request field;
• adding a field to a response (clients must ignore fields they do not know);
• adding a new value to an enum, if clients were told to handle unknown values.

Breaking changes (need a new version or a migration plan):

• removing or renaming a field;
• changing a field's type or meaning;
• making an optional field required;
• changing status codes or error formats that clients rely on.

Common ways to express versions:

Whatever you choose, the harder part is process: announce deprecations, monitor which clients still use old versions, and keep old versions running long enough for mobile apps to update. Microsoft's API design guidance covers these practices in more depth (Web API design best practices).

REST is a good default, not the only option.

A reasonable interview position: "REST for the public API, gRPC between internal services if latency and strict contracts matter, and WebSockets for the real-time channel." Then justify each.

Here is how the Interface phase looks for Pixly. In an interview you would write the first column and talk through the rest.

Notice two deliberate choices:

• Likes and follows use PUT on a resource that represents "my like", which makes them naturally idempotent. Liking twice leaves you with one like, and retries are harmless. A POST /likes design would need extra deduplication.
• The feed uses cursor pagination, because it is a large, constantly changing list read with infinite scroll.

This fragment shows how such an API is often expressed in Java with Spring. It is an illustration, not a complete program: services, validation annotations and error handling are left out. The same API could be written in any language.

@RestController@RequestMapping("/v1")class PhotoController {    private final PhotoService photos;    PhotoController(PhotoService photos) {        this.photos = photos;    }    @PostMapping("/photos")    ResponseEntity<CreatePhotoResponse> create(            @RequestHeader("Idempotency-Key") String idempotencyKey,            @Valid @RequestBody CreatePhotoRequest request,            @AuthenticationPrincipal User caller) {        CreatePhotoResponse created = photos.create(caller.id(), request, idempotencyKey);        return ResponseEntity.created(URI.create("/v1/photos/" + created.photoId())).body(created);    }    @GetMapping("/feed")    FeedPage feed(@RequestParam(required = false) String cursor,                  @RequestParam(defaultValue = "20") int limit,                  @AuthenticationPrincipal User caller) {        int pageSize = Math.min(Math.max(limit, 1), 100); // cap the page size        return photos.feed(caller.id(), cursor, pageSize);    }    @PutMapping("/photos/{photoId}/likes/me")    ResponseEntity<Void> like(@PathVariable String photoId, @AuthenticationPrincipal User caller) {        photos.like(caller.id(), photoId); // idempotent: liking twice leaves one like        return ResponseEntity.noContent().build();    }}

The interesting design decisions are all visible without the rest of the code: the idempotency key on creation, the capped page size, the 201 with a Location, and the idempotent PUT for likes.

• Verbs in URLs (/createPhoto) instead of methods on resources.
• 200 OK with an error message in the body. Clients, proxies and monitoring then think the call succeeded.
• Non-idempotent creation without a key. Retries on flaky networks create duplicates, which is the most common real-world failure this article prevents.
• Unbounded lists with no pagination or page-size cap.
• Offset pagination on infinite feeds, producing duplicates and slow deep pages.
• Breaking changes without a version, which fail silently on old mobile apps that cannot be forced to update.
• Leaking internals in errors: stack traces, SQL, server names.
• Checking authentication but not authorisation per object, so any signed-in user can read anyone's data by changing an id.

• List four to six endpoints that cover the functional requirements. Do not design twenty.
• For each, state method, path, the key request fields and the success response.
• Point out any endpoint that must be idempotent and how you make it so.
• Mention pagination for lists, and authentication and rate limiting once for the whole API.
• If the system has real-time needs, say which channel carries them (article 05).

POST /getUser            body: {"id": 42}POST /createOrder        body: {...}POST /deleteOrder        body: {"orderId": 77}GET  /cancelOrder?id=77POST /addItemToCart      body: {"cartId": 5, "productId": 9, "qty": 2}

GET    /users/42                      -> 200 with the userPOST   /orders                        -> 201 Created, Location: /orders/{orderId}DELETE /orders/77                     -> 204 No Content (or keep the record and use cancellation)POST   /orders/77/cancellation        -> 201 or 200, or PATCH /orders/77 {"status": "cancelled"}PUT    /carts/5/items/9  {"qty": 2}   -> 200 or 204

• Next: Synchronous vs Asynchronous Communication: Queues, Polling, WebSockets and Server-Sent Events decides how long requests and real-time updates should work.
• If APIs are new to you, What Is an API? A Plain-English Explanation With Real Examples starts from zero.
• Later: idempotency in depth (article 20), optimistic concurrency (article 14), API security (article 28) and rate limiting (article 31).