API Design Study Portal

How it works

Choosing between REST, gRPC and GraphQL

This is a "who is calling, over what network" question, not a taste question.

REST's underrated advantage is that it works with the HTTP caching ecosystem. A GET with a sensible Cache-Control header can be served by a CDN, a reverse proxy, and the browser without your servers being involved. GraphQL loses this almost entirely, because everything is a POST to a single endpoint and the response depends on the query body — so caching moves into your application, where you have to build it.

gRPC's cost is that it is inconvenient from a browser and opaque to ordinary HTTP tooling, which is precisely why it belongs behind your edge rather than at it.

Pagination: why offset breaks

LIMIT 20 OFFSET 10000 has two problems. The database must scan and discard 10,000 rows to return 20, so deep pages get progressively slower. Worse, on data that changes while the user pages, offsets shift: if a row is inserted before the current page, one item moves to the next page and the user sees a duplicate; if a row is deleted, an item is skipped entirely and never seen.

Cursor-based (keyset) pagination fixes both by remembering where you were rather than how many you skipped.

-- Offset pagination: page 500 forces the database to walk 10,000 rows first.
SELECT id, title, created_at
FROM   posts
WHERE  feed_id = $1
ORDER  BY created_at DESC, id DESC
LIMIT  20 OFFSET 10000;

-- Keyset pagination: uses the index to seek directly, and cannot skip or duplicate.
SELECT id, title, created_at
FROM   posts
WHERE  feed_id = $1
  AND  (created_at, id) < ($2, $3)   -- the cursor from the previous page
ORDER  BY created_at DESC, id DESC
LIMIT  20;

Two details make this work. The sort key must be unique, which is why id is included as a tiebreaker — with only created_at, two rows sharing a timestamp can straddle a page boundary and be lost or repeated. And the cursor should be opaque to the client, typically base64-encoded, so that clients do not build logic on its internals and you can change the sort without breaking them.

Idempotency, and why it is mandatory

When a client sends a request and the connection times out, the client cannot tell whether the server processed it. The request may have succeeded and the response been lost. The only safe options are to retry — which risks doing the operation twice — or to give up, which risks losing it.

GET, PUT and DELETE are idempotent by definition: repeating them yields the same state. POST is not, which is why payment and order-creation endpoints need an explicit mechanism: the client generates a unique key and sends it with the request, and the server records the key with the result.

// The server side of an idempotency key. The important part is that
// the key is reserved ATOMICALLY before any work happens.
public async Task<IActionResult> CreatePayment(PaymentRequest request, string idempotencyKey)
{
    var existing = await _store.TryGetAsync(idempotencyKey);
    if (existing is not null)
    {
        // Replay the original outcome verbatim — do not re-execute.
        return StatusCode(existing.StatusCode, existing.Body);
    }

    // Atomic insert-if-absent. If this loses the race, another request
    // with the same key is already in flight.
    var reserved = await _store.TryReserveAsync(idempotencyKey, ttl: TimeSpan.FromHours(24));
    if (!reserved)
    {
        return StatusCode(409, new { error = "request_in_progress" });
    }

    var result = await _payments.ChargeAsync(request);
    await _store.CompleteAsync(idempotencyKey, result);
    return Ok(result);
}

The subtle requirement is that the reservation must be atomic. A naive "check whether the key exists, then insert it" has a window in which two concurrent retries both see no key and both charge the card. The check and the reservation must be one operation — a conditional insert, or a unique constraint that the second writer violates.

Versioning without breaking clients

Once a third party depends on your API you cannot change it, only add to it. The practical rules are narrower than the versioning debate suggests.

Adding an optional field is safe. Adding a required request field, removing a field, renaming anything, changing a type, or tightening validation are all breaking. So is changing the meaning of an existing field while keeping its name and type — which is the most dangerous kind, because nothing fails at compile time and nobody notices until the data is wrong.

URL-path versioning (/v1/, /v2/) is the most common choice because it is visible, trivially routable at layer 7, and easy to reason about in logs and caches. Header-based versioning keeps URLs stable and is arguably purer, but it is easier to get wrong operationally, since a missing header silently selects a default.

Designing errors as part of the contract

Error responses are consumed by code, so they need structure. A useful shape has a stable machine-readable code that clients branch on, a human-readable message that you are free to reword, and enough detail to act — plus, critically, an indication of whether retrying is sensible.

The distinction that matters most operationally is between errors the client caused and errors the server caused, because it determines who is paged and whether a retry helps. A 400 means the request was wrong and retrying it unchanged will fail identically. A 503 or 429 means try again later, ideally with Retry-After so the client does not have to guess and does not retry aggressively enough to prolong the outage.

Quick recall

Short-answer versions of the same material, for spaced repetition.