API design basics: 50 cards on REST, status codes and auth

All 50 cards

1. 1
   What is REST?
   An architectural style for networked APIs, described by Roy Fielding in 2000: resources identified by URLs and manipulated through a uniform interface of standard HTTP methods

   Its constraints: client-server, stateless, cacheable, uniform interface, layered system, and optional code on demand.
2. 2
   How should REST endpoints be named?
   Nouns for resources, plural for collections, and HTTP methods for the action: GET /users, GET /users/42, POST /users/42/orders

   Avoid verbs in paths, like /getUser or /createOrder.
3. 3
   What does “stateless” mean for a REST API?
   Each request carries everything the server needs to handle it, such as the auth token; the server keeps no client session between requests

   Any server instance can then handle any request, which makes scaling out easy.
4. 4
   HATEOAS
   Hypermedia as the engine of application state: responses include links to related resources and available actions, so clients follow links instead of hard-coding URLs

   It’s the strictest REST constraint and is rarely implemented in full.
5. 5
   Filtering, sorting and selecting fields in a REST API
   Query parameters on the collection, e.g. GET /orders?status=shipped&sort=-created_at&fields=id,total
6. 6
   What do GET, POST, PUT, PATCH and DELETE do?
   GET reads, POST creates (or triggers processing), PUT replaces, PATCH partially updates, DELETE removes
7. 7
   Which HTTP methods are safe?
   GET, HEAD and OPTIONS (and TRACE): they must not change server state

   Crawlers and link prefetchers assume safe methods are harmless, so never let a GET delete or modify data.
8. 8
   Which HTTP methods are idempotent?
   GET, HEAD, OPTIONS, PUT and DELETE. POST is not, and PATCH isn’t guaranteed to be

   Idempotency is about server state, not the response: a repeated DELETE may return 404 and is still idempotent.
9. 9
   PUT vs PATCH
   PUT replaces the whole resource with the request body; PATCH applies a partial change, such as updating only the fields sent

   Common PATCH formats are JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902).
10. 10
    Creating a resource: POST vs PUT
    POST /users when the server assigns the ID; PUT /users/alice when the client chooses the URL (PUT creates or replaces)
11. 11
    The five classes of HTTP status codes
    1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error
12. 12
    200 vs 201 vs 204
    200 OK, with a response body. 201 Created, usually with a Location header pointing to the new resource. 204 No Content: success with an empty body
13. 13
    400 vs 422
    400 Bad Request: the request is malformed, e.g. invalid JSON. 422 Unprocessable Content: it’s well-formed but fails validation

    Many APIs use 400 for both; pick one convention and document it.
14. 14
    401 vs 403
    401 Unauthorized: not authenticated (credentials missing or invalid). 403 Forbidden: authenticated, but not allowed to do this

    Despite its name, 401 is about authentication. Some APIs answer 404 instead of 403 to avoid revealing that a resource exists.
15. 15
    404 vs 405
    404 Not Found: nothing exists at this URL. 405 Method Not Allowed: the resource exists but doesn’t support this method, and the response must list the allowed ones in an Allow header
16. 16
    When should an API return 409 Conflict?
    When the request conflicts with the resource’s current state, e.g. signing up with a username that’s taken, or updating a record that changed in the meantime
17. 17
    500 vs 502 vs 503 vs 504
    500: an unexpected server error. 502 Bad Gateway: a proxy got an invalid response from upstream. 503 Service Unavailable: overloaded or down for maintenance. 504 Gateway Timeout: the upstream didn’t answer in time
18. 18
    How do ETags make repeated GET requests cheaper?
    The server sends an ETag (a version tag); the client sends it back in If-None-Match, and if nothing changed the server answers 304 Not Modified with no body
19. 19
    How do you prevent lost updates when two clients edit the same resource?
    Optimistic concurrency: send If-Match with the ETag you read. If the resource changed since then, the server rejects the write with 412 Precondition Failed

    Without such a check, the last write silently overwrites the other client’s changes.
20. 20
    Standard format for API error responses
    Problem Details (RFC 9457): a JSON body served as application/problem+json

    json

    {
      "type": "https://example.com/errors/out-of-credit",
      "title": "You do not have enough credit.",
      "status": 403,
      "detail": "Your balance is 30, but that costs 50."
    }

21. 21
    Offset vs cursor pagination
    Offset (?limit=20&offset=40) is simple and can jump to any page, but slows down at large offsets and skips or repeats items when data changes. Cursor (?limit=20&after=abc123) is fast and stable, but only moves to the next or previous page
22. 22
    Keyset (cursor) pagination in SQL
    sql

    SELECT * FROM posts
    WHERE (created_at, id) < (:last_created_at, :last_id)
    ORDER BY created_at DESC, id DESC
    LIMIT 20;

    The cursor encodes the sort key of the last row returned. Including id breaks ties, and an index on (created_at, id) keeps every page fast.
23. 23
    How do API clients find the next page?
    Return a cursor or URL for the next page in the body (e.g. "next_cursor": "abc123"), or a Link header with rel="next", as GitHub does

    Leave the cursor out (or null) on the last page so clients know when to stop.
24. 24
    Three common ways to version an API
    In the URL path (/v1/users), in a header (e.g. Accept: application/vnd.example.v2+json), or as a query parameter (?version=2)

    Path versioning is the most common because it’s explicit and easy to route, cache and test.
25. 25
    Breaking vs non-breaking API changes
    Breaking: removing or renaming fields, changing types or meanings, adding required parameters. Non-breaking: adding endpoints, optional parameters or new response fields

    New fields are only safe if clients ignore fields they don’t recognize, so tell them to.
26. 26
    How do you retire an old API version gracefully?
    Announce a timeline, flag it in responses with Deprecation and Sunset headers, watch who still calls it, and only then switch it off

    The Sunset header (RFC 8594) gives the date the endpoint will stop working.
27. 27
    Authentication vs authorization
    Authentication checks who you are; authorization decides what you’re allowed to do
28. 28
    When do API keys fit, and how should they be sent?
    For identifying a calling application or project, e.g. server-to-server calls and usage metering. Send them in a header, never in the URL

    An API key identifies an app, not a user, and can’t express a user’s consent; use OAuth for delegated access.
29. 29
    What problem does OAuth 2.0 solve?
    Delegated authorization: a user lets an app access their data at another service, limited by scopes, without giving the app their password

    The app receives an access token and sends it with each call as Authorization: Bearer <token>.
30. 30
    The four OAuth 2.0 roles
    Resource owner (the user), client (the app), authorization server (issues tokens), resource server (the API that accepts them)
31. 31
    Which OAuth 2.0 flow should web, mobile and single-page apps use?
    Authorization code with PKCE: the user signs in at the authorization server, and the app exchanges the short-lived code it gets back, together with a secret code verifier, for tokens

    PKCE stops an intercepted code from being redeemed by an attacker. The older implicit flow is deprecated.
32. 32
    OAuth 2.0 flow for machine-to-machine calls with no user
    Client credentials: the service authenticates with its own client ID and secret to get an access token
33. 33
    OAuth 2.0 vs OpenID Connect
    OAuth 2.0 handles authorization (access tokens for APIs). OpenID Connect adds an identity layer on top, with an ID token (a JWT) saying who signed in

    “Sign in with Google” uses OpenID Connect.
34. 34
    Structure of a JWT
    Three base64url parts joined by dots, header.payload.signature. The payload holds claims such as sub, exp, iss and aud

    A typical JWT is signed, not encrypted: anyone can decode and read the payload, so never put secrets in it.
35. 35
    What must a server check when it receives a JWT?
    The signature, using the algorithm it expects (never accept alg: none), plus the expiry (exp), the issuer (iss) and the audience (aud)
36. 36
    Access token vs refresh token
    Access tokens are short-lived (minutes) and sent with every API call. Refresh tokens live longer and are sent only to the authorization server, to get new access tokens

    Short lifetimes limit the damage of a leaked token, because a self-contained JWT can’t easily be revoked before it expires.
37. 37
    What is CORS?
    Cross-Origin Resource Sharing: a way for a server to tell browsers which other origins may read its responses, using headers such as Access-Control-Allow-Origin

    An origin is scheme + host + port. Without CORS headers, the browser’s same-origin policy stops scripts from reading cross-origin responses.
38. 38
    When does a browser send a CORS preflight request?
    Before a cross-origin request that isn’t “simple”, e.g. PUT or DELETE, a Content-Type: application/json body, or custom headers. It sends OPTIONS to ask whether that method and those headers are allowed

    Access-Control-Max-Age lets the browser cache the answer.
39. 39
    CORS rules for requests that send cookies
    The server must send Access-Control-Allow-Credentials: true and name the exact origin; Access-Control-Allow-Origin: * isn’t allowed with credentials

    Only browsers enforce CORS. It doesn’t protect an API from curl or other servers; that’s the job of authentication.
40. 40
    How should an API tell clients they hit a rate limit?
    Respond with 429 Too Many Requests and a Retry-After header

    Many APIs also send headers like X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so clients can slow down before they hit the limit.
41. 41
    How do you make POST /payments safe to retry?
    The client sends a unique Idempotency-Key header; the server stores the first result for that key and returns it for any retry instead of charging again

    Stripe popularized this pattern, and the IETF is standardizing the header.
42. 42
    What is OpenAPI?
    A standard, machine-readable format (YAML or JSON) for describing HTTP APIs: endpoints, parameters, request and response schemas, and authentication

    Formerly called Swagger. One spec can drive docs, client and server code generation, request validation and mock servers.
43. 43
    What does this OpenAPI snippet describe?

    yaml

    paths:
      /users/{id}:
        get:
          parameters:
            - name: id
              in: path
              required: true
              schema:
                type: integer
          responses:
            "200":
              description: The user
            "404":
              description: No such user

    A GET /users/{id} endpoint with a required integer path parameter id, which responds with 200 (the user) or 404
44. 44
    What is gRPC?
    An RPC framework that sends Protocol Buffers messages over HTTP/2. Services are defined in .proto files that generate typed clients and servers, with streaming in either or both directions

    Fast and strongly typed, it’s popular between internal services. Browsers can’t call it directly and need a bridge such as gRPC-Web.
45. 45
    What is GraphQL?
    A query language for APIs: clients send queries to a single endpoint and get back exactly the fields they asked for, checked against a typed schema

    It avoids over-fetching (too much data) and under-fetching (several round trips), but makes HTTP caching and rate limiting harder.
46. 46
    REST vs GraphQL vs gRPC: which fits?
    REST for public, resource-oriented, cacheable APIs; GraphQL when varied clients need flexible, nested data in one request; gRPC for fast, typed service-to-service calls and streaming
47. 47
    The N+1 problem in GraphQL
    Resolving a list and then a field on each item runs one query for the list plus one more per item

    Batch and cache those lookups per request with a DataLoader.
48. 48
    What is a webhook?
    An HTTP callback: when an event happens, the provider sends a POST to a URL you registered, so you don’t have to poll for changes
49. 49
    How do you verify that a webhook really came from the provider?
    Check its signature: compute an HMAC of the raw request body with the shared secret and compare it, in constant time, with the signature header, such as GitHub’s X-Hub-Signature-256

    Also reject old timestamps to block replayed requests, and accept webhooks only over HTTPS.
50. 50
    Best practices for receiving webhooks
    Return a 2xx quickly and do the work asynchronously, deduplicate by event ID because providers retry, and don’t assume events arrive in order