API styles and HTTP semantics for designers

An API style decides how a client names what it wants: a resource at a URL (REST), a typed procedure (RPC, today usually gRPC) or a query over a graph of types (GraphQL). Choose it by who calls the API: REST for partners and the open web, gRPC for services you own on both ends, GraphQL for client screens that need different slices of the same data. HTTP semantics are the promises underneath that every client, cache and proxy relies on without reading your documentation: which methods may be repeated, and what each status code tells software to do next. Get those right and retries, caches and monitoring work for you; get them wrong and a timeout can charge a customer twice.

This lesson compares the three styles, then the parts of RFC 9110 that a designer has to get exactly right.

Three styles for one request

Here is the same read, order 42 with its status and total, in each style.

REST models the system as resources with addresses, and acts on them with HTTP’s uniform methods: GET /orders/42 reads the order, PUT replaces it, DELETE removes it. The response is a representation, usually JSON, and its status code and headers mean what RFC 9110 says they mean, which is why caches, proxies and generic tools can work with any REST API without knowing it.

gRPC models the system as services with methods, declared in a .proto file, from which it generates client and server code in many languages. By default the messages are Protocol Buffers, and the core concepts name four kinds of method: unary, server streaming, client streaming and bidirectional streaming. On the wire every call is an HTTP/2 POST to /Service/Method, and its outcome travels as grpc-status in the trailers (gRPC over HTTP2), not as the HTTP status.

GraphQL publishes one schema of types and lets each client ask for exactly the fields it needs, in one request to one endpoint. The specification defines three operations: a query reads, a mutation writes and then reads, a subscription delivers results as events happen. That freedom moves work to the server: one innocent-looking query can fan out into thousands of database reads, so the server has to measure and limit what each query may cost.

How each one fits a client and a team

The style is a choice about clients and teams as much as about technology. A public API serves programs you will never see, written with plain HTTP libraries and sitting behind caches you do not control, so REST’s reliance on standard HTTP is its main asset. Inside a company the trade turns around: you own both ends, a generated client in Go, Java or Python removes a whole class of mismatched-field bugs, and gRPC’s deadlines travel with each call. GraphQL earns its cost where many client screens draw on many back ends and the screens change every release.

Mixing styles is normal. A common shape is REST at the edge for partners, gRPC between internal services, and either GraphQL or a small backend for each app screen, so that a phone makes one request instead of six.

A worked example. An app’s home screen needs data from six services, and a phone on a mobile network has a round trip of about 150 ms to your servers (an assumption; measure your own users). Six REST calls made one after another spend about 6 × 150 = 900 ms waiting on the network alone. Sent in parallel over one HTTP/2 connection they cost about one round trip, but the app still has to know six APIs and survive six partial failures. A GraphQL server or a screen-specific backend in the data centre makes the same six calls over links whose round trip is well under a millisecond, so the phone waits about one round trip plus the slowest of the six calls, and it receives only the fields the screen shows.

Safe and idempotent: what software may assume

RFC 9110 gives each method two properties that the whole HTTP ecosystem relies on.

• A safe method only reads: the client does not ask for, and does not expect, any change of state. GET, HEAD, OPTIONS and TRACE are safe (section 9.2.1), so crawlers, link prefetchers and caches may send or repeat them freely.
• An idempotent method has the same intended effect on the server whether it arrives once or several times. PUT, DELETE and the safe methods are idempotent (section 9.2.2), so a client may repeat one by itself when the connection fails before a response arrives.

The example below calls a small in-memory API twice per request, the second time as an automatic retry would after a lost reply, and compares the server’s state after each call:

// A tiny in-memory API, called twice per request: once, then again as an automatic retry would after a lost reply.
// It checks what RFC 9110 promises: repeating an idempotent request leaves the server as one copy did.

function newServer() {
  const state = { orders: {}, nextOrder: 1, profiles: {}, sessions: { s1: { user: 7 } }, views: 0 };
  const handlers = {
    'GET /orders': () => ({ status: 200 }),
    'PUT /profiles/7': (body) => {
      const existed = '7' in state.profiles;
      state.profiles['7'] = { ...body }; // PUT replaces the whole resource with the body
      return { status: existed ? 200 : 201 };
    },
    'DELETE /sessions/s1': () => {
      if (!('s1' in state.sessions)) return { status: 404 };
      delete state.sessions.s1;
      return { status: 204 };
    },
    'POST /orders': (body) => {
      const id = state.nextOrder++; // the server picks the new order's address
      state.orders[id] = { ...body };
      return { status: 201, location: `/orders/${id}` };
    },
    'PATCH /counters/views': (body) => {
      if (body.op === 'increment') state.views += 1; // a relative change
      return { status: 200 };
    },
    'PATCH /profiles/7': (body) => {
      if (!('7' in state.profiles)) return { status: 404 };
      Object.assign(state.profiles['7'], body); // sets the fields given, to absolute values
      return { status: 200 };
    },
  };
  const call = (method, path, body = {}) => handlers[`${method} ${path}`](body);
  return { state, call };
}

/** The server's state as text, with keys sorted, so two states can be compared. */
function snapshot(value) {
  if (value === null || typeof value !== 'object') return JSON.stringify(value);
  const keys = Object.keys(value).sort();
  return `{${keys.map((k) => `${JSON.stringify(k)}:${snapshot(value[k])}`).join(',')}}`;
}

const requests = [
  ['GET', '/orders', {}, 'safe: reads only'],
  ['PUT', '/profiles/7', { name: 'Asha', city: 'Pune' }, 'idempotent'],
  ['DELETE', '/sessions/s1', {}, 'idempotent'],
  ['POST', '/orders', { sku: 'tea-250g', qty: 1 }, 'neither'],
  ['PATCH', '/counters/views', { op: 'increment' }, 'neither'],
  ['PATCH', '/profiles/7', { city: 'Nagpur' }, 'neither, but this patch sets a value'],
];

const server = newServer();
console.log('request                    1st    retry  state after the retry');
for (const [method, path, body, promise] of requests) {
  const first = server.call(method, path, body);
  const afterFirst = snapshot(server.state);
  const retry = server.call(method, path, body); // the same request again
  const same = snapshot(server.state) === afterFirst;
  const label = `${method.padEnd(6)} ${path}`.padEnd(26);
  const verdict = same ? 'same as after the 1st' : 'CHANGED by the retry';
  console.log(`${label} ${String(first.status).padEnd(6)} ${String(retry.status).padEnd(6)} ${verdict} (${promise})`);
}

console.log(`\norders created: ${Object.keys(server.state.orders).length} (the client wanted 1)`);
console.log(`view counter: ${server.state.views} (the client sent one increment)`);
console.log(`profile 7: ${snapshot(server.state.profiles['7'])}`);

request                    1st    retry  state after the retry
GET    /orders             200    200    same as after the 1st (safe: reads only)
PUT    /profiles/7         201    200    same as after the 1st (idempotent)
DELETE /sessions/s1        204    404    same as after the 1st (idempotent)
POST   /orders             201    201    CHANGED by the retry (neither)
PATCH  /counters/views     200    200    CHANGED by the retry (neither)
PATCH  /profiles/7         200    200    same as after the 1st (neither, but this patch sets a value)

orders created: 2 (the client wanted 1)
view counter: 2 (the client sent one increment)
profile 7: {"city":"Nagpur","name":"Asha"}

Three design rules follow from the output.

• Never change state on GET. A GET /orders/42/cancel link that cancels an order will one day be followed by a prefetcher or a crawler, and a retry of it is never questioned.
• Prefer PUT when the client can choose the address. A client that generates the order’s id and sends PUT /orders/<id> can repeat the request safely; with POST /orders the server picks a new id every time, so the retry in the output created a second order. POST stays the right method when the server must choose, and a later lesson of this module shows how an idempotency key makes its retries safe.
• Write patches that set values, not patches that change them. RFC 5789 defines PATCH as neither safe nor idempotent, but the output shows that a patch setting city to a value behaves idempotently, while “increment the counter” does not.

Idempotent describes the state, not the reply: the retried DELETE got 404, yet the session is gone either way. RFC 9110 also says that a client should not retry a non-idempotent request automatically unless it knows the request is harmless to repeat or knows the first attempt never took effect, and that a proxy must never do so.

Status codes clients act on

A status code is an instruction to software that will never read your documentation: try again, wait, sign in again, fix the request or give up. Choose each code by what the caller should do next.

Rate limiting has its own code. RFC 6585 defines 429 for a user who “has sent too many requests in a given amount of time”, says the response should explain the condition and may carry Retry-After, and deliberately leaves open how the server identifies the user and counts requests: per API key, per account or per address are all yours to choose. Retry-After holds either a number of seconds (Retry-After: 30) or an HTTP date (section 10.2.3), and 503 may carry it too. Send it every time: a client that knows when to come back does not have to guess, and guessing clients retry too early.

The exercise asks you to turn the last two sections into the two functions every client library needs: whether it may repeat a request on its own, and how long it should wait first.

"""Retry rules for an HTTP client: which requests it may repeat on its own, and how long it waits first."""

from email.utils import parsedate_to_datetime


def may_retry(method, status, idempotency_key=False):
    """True when the client may send the same request again on its own.

    status is the response's status code, or None when no response arrived (a timeout or a dropped connection).
    """
    # Replace this line with your code.
    return False


def retry_delay(headers, now):
    """Seconds to wait before a retry, from the Retry-After header, or None when it is missing or invalid.

    headers maps header names (in any letter case) to values; now is a timezone-aware datetime.
    """
    # Replace this line with your code.
    return None

from datetime import datetime, timezone

from retry import may_retry, retry_delay

NOW = datetime(2026, 1, 15, 10, 0, 0, tzinfo=timezone.utc)


def test_idempotent_methods_after_no_response():
    """repeats idempotent methods when no response arrived"""
    assert may_retry("GET", None) is True
    assert may_retry("put", None) is True
    assert may_retry("DELETE", None) is True


def test_post_needs_a_key():
    """repeats POST only with an idempotency key"""
    assert may_retry("POST", None) is False
    assert may_retry("POST", 503) is False
    assert may_retry("POST", 503, idempotency_key=True) is True


def test_status_codes():
    """retries overload and gateway errors, never client errors or plain successes"""
    assert may_retry("GET", 429) is True
    assert may_retry("GET", 504) is True
    assert may_retry("GET", 404) is False
    assert may_retry("PUT", 409) is False
    assert may_retry("GET", 200) is False


def test_delay_in_seconds():
    """reads a number of seconds, in any header case"""
    assert retry_delay({"Retry-After": "30"}, NOW) == 30
    assert retry_delay({"retry-after": "120"}, NOW) == 120
    assert retry_delay({"Retry-After": "0"}, NOW) == 0


def test_delay_as_a_date():
    """counts the seconds until an HTTP date, and 0 for a date in the past"""
    assert retry_delay({"Retry-After": "Thu, 15 Jan 2026 10:01:30 GMT"}, NOW) == 90
    assert retry_delay({"Retry-After": "Thu, 15 Jan 2026 09:00:00 GMT"}, NOW) == 0


def test_missing_or_invalid():
    """returns None when there is no usable value"""
    assert retry_delay({}, NOW) is None
    assert retry_delay({"Retry-After": "-5"}, NOW) is None
    assert retry_delay({"Retry-After": "soon"}, NOW) is None

One error body everywhere: problem details

Status codes give the kind of failure; a program also needs to know which failure it was. Instead of inventing a format per team, use RFC 9457, which defines the media type application/problem+json and five members, all optional: type (a URI that names the problem and is its main identifier), title (a short summary of the type), status, detail (about this occurrence, for people) and instance (this occurrence’s URI). A body without type means about:blank, a problem with no meaning beyond its status code. Problem types may add their own members, and clients must ignore members they do not know, so the format can grow without breaking anyone.

"""Three error responses in the problem details format of RFC 9457, checked against the RFC's rules."""

import json
import re

HOST = "https://api.example.com"
REASONS = {404: "Not Found", 409: "Conflict", 422: "Unprocessable Content", 429: "Too Many Requests"}
MEMBER_TYPES = {"type": str, "title": str, "status": int, "detail": str, "instance": str}
# RFC 9457 section 3.2: extension names should start with a letter, use letters, digits and "_", and be 3+ long.
GOOD_EXTENSION_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_]{2,}")


def problem(status, headers, body):
    return {"status": status, "headers": {"Content-Type": "application/problem+json", **headers}, "body": body}


responses = [
    problem(422, {}, {
        "type": f"{HOST}/problems/invalid-fields",
        "title": "Some fields are not valid",
        "status": 422,
        "detail": "2 fields failed validation.",
        "instance": "/orders",
        "errors": [
            {"pointer": "/qty", "detail": "must be between 1 and 20"},
            {"pointer": "/email", "detail": "must be an email address"},
        ],
    }),
    problem(429, {"Retry-After": "30"}, {
        "type": f"{HOST}/problems/rate-limited",
        "title": "Too many requests for this key",
        "status": 429,
        "detail": "This key may send 100 requests a minute; try again in 30 seconds.",
        "limit_per_minute": 100,
    }),
    problem(409, {}, {
        "type": f"{HOST}/problems/version-conflict",
        "title": "The order changed since you read it",
        "status": 409,
        "detail": "You edited version 3; the order is at version 4.",
        "instance": "/orders/1842",
        "current_version": 4,
    }),
    # No "type": a client must treat it as "about:blank", which adds nothing to the status code.
    problem(404, {}, {"title": "Not Found", "status": 404}),
]


def check(response):
    body, status = response["body"], response["status"]
    problems = []
    for name, kind in MEMBER_TYPES.items():
        if name in body and not isinstance(body[name], kind):
            problems.append(f"{name} should be a {kind.__name__}")
    if body.get("status", status) != status:
        problems.append("the status member differs from the HTTP status code")
    if body.get("type", "about:blank") == "about:blank" and body.get("title") != REASONS[status]:
        problems.append("with about:blank the title should be the status code's reason phrase")
    for name in body.keys() - MEMBER_TYPES.keys():
        if not GOOD_EXTENSION_NAME.fullmatch(name):
            problems.append(f"extension name {name!r} breaks the naming advice")
    return problems or ["ok"]


for response in responses:
    print(f"HTTP/1.1 {response['status']} {REASONS[response['status']]}")
    for name, value in response["headers"].items():
        print(f"{name}: {value}")
    print(json.dumps(response["body"], indent=2))
    kind = response["body"].get("type", "about:blank")
    print(f"-- type {kind.removeprefix(HOST)}; checks: {'; '.join(check(response))}\n")

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
  "type": "https://api.example.com/problems/invalid-fields",
  "title": "Some fields are not valid",
  "status": 422,
  "detail": "2 fields failed validation.",
  "instance": "/orders",
  "errors": [
    {
      "pointer": "/qty",
      "detail": "must be between 1 and 20"
    },
    {
      "pointer": "/email",
      "detail": "must be an email address"
    }
  ]
}
-- type /problems/invalid-fields; checks: ok

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30
{
  "type": "https://api.example.com/problems/rate-limited",
  "title": "Too many requests for this key",
  "status": 429,
  "detail": "This key may send 100 requests a minute; try again in 30 seconds.",
  "limit_per_minute": 100
}
-- type /problems/rate-limited; checks: ok

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
  "type": "https://api.example.com/problems/version-conflict",
  "title": "The order changed since you read it",
  "status": 409,
  "detail": "You edited version 3; the order is at version 4.",
  "instance": "/orders/1842",
  "current_version": 4
}
-- type /problems/version-conflict; checks: ok

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
  "title": "Not Found",
  "status": 404
}
-- type about:blank; checks: ok

The output shows the rules that make the format useful: the status member matches the HTTP status, every machine-readable fact (the field errors, the limit, the current version) has a member of its own, and detail is written for people. Clients branch on type and those members, never on the wording of detail, so you can reword a message without breaking an integration.

When the style hides HTTP semantics

gRPC and GraphQL both carry their own outcome inside an HTTP 200, so the generic HTTP machinery that the earlier sections relied on sees much less.

• gRPC reports the outcome as one of 17 codes in grpc-status, while the HTTP status stays 200. Its status code guide calls UNAVAILABLE most likely a transient condition, which a retry with backoff can fix, but warns that retrying non-idempotent operations is not always safe, and that DEADLINE_EXCEEDED may come back even when a state-changing call succeeded. The rules of the methods table still apply; you write them into each method’s contract instead of getting them from the HTTP method. Browsers reach gRPC services only through gRPC-Web and a proxy, and the gRPC-Web README lists unary and server-streaming calls only.
• GraphQL reports a field that fails during execution by setting it to null and adding an entry to the errors list with the field’s path, so one response can be partly successful. Many servers answer 200 whenever any data came back, so dashboards that count HTTP 5xx miss these failures: count the errors entries instead. The GraphQL over HTTP working draft asks for a 4xx or 5xx status when no data could be produced at all, and lets queries, never mutations, travel as GET, which is what makes them cacheable.

Interview questions

Fresher · How do REST, gRPC and GraphQL differ?

REST exposes resources at URLs and acts on them with HTTP’s methods, so caches, proxies and any HTTP client understand it. gRPC exposes typed methods declared in a .proto file, generates clients in many languages and runs over HTTP/2 with Protocol Buffers, with streaming and deadlines built in, which suits calls between services you own. GraphQL publishes one schema and lets each client pick the fields it needs in a single request, which suits screens that combine many back ends, at the price of controlling query cost and caching on the server.

Fresher · A response is 429 with Retry-After: 30. What should the client do?

Stop sending that request for at least 30 seconds, because the server says this client has exceeded its rate limit. Then retry with backoff and some random jitter, so that many clients do not return at the same moment, and slow its overall request rate. The response does not mean the request was invalid: the same request should succeed later, so an idempotent request, or a POST that carries an idempotency key, can be retried automatically after the wait.

Key takeaways

• Choose the style by audience: REST for partners and the open web, gRPC between services you own, GraphQL (or a backend per screen) where screens combine many services.
• GET, HEAD, OPTIONS and TRACE are safe; they and PUT and DELETE are idempotent and may be repeated automatically. POST and PATCH are neither, so their retries need another guarantee.
• Pick status codes by what the client should do next; send Retry-After with 429 and 503.
• Use one error format, RFC 9457 problem details, with a type per problem and machine-readable members.
• gRPC and GraphQL carry their outcome inside HTTP 200, so retry rules and monitoring must read grpc-status or the errors list instead.