Skip to content

Interview PrepREST API design · Advanced

API Design in Detail ​

50. How do you design pagination for an API? ​

The short answer

Never return an unbounded list. Every collection endpoint takes a page size, limit, with a sensible default and a hard maximum, plus a way to ask for the next page: an offset or page number, or better, an opaque cursor. Return the items together with what the client needs to continue, such as nextCursor or a next link, and whether more items exist. Keep the sort order stable and deterministic, by adding a unique tie-breaker such as the ID, so pages never skip or repeat items.

http
GET /orders?limit=20&cursor=eyJjIjoiMjAyNi0xMC0yN1QxMDowMDowMFoiLCJpZCI6Im9yZF80MiJ9
json
{
  "data": [ { "id": "ord_42", "createdAt": "2026-10-27T10:00:00Z", "totalPence": 2499 } ],
  "page": {
    "limit": 20,
    "nextCursor": "eyJjIjoiMjAyNi0xMC0yNlQxODozMDowMFoiLCJpZCI6Im9yZF8zOSJ9",
    "hasMore": true
  },
  "links": { "next": "/orders?limit=20&cursor=eyJj…" }
}

Design rules:

RuleWhy
Default limit, maximum limit?limit=1000000 must not take down the database
Stable sort with a tie-breakerORDER BY created_at DESC, id DESC: equal timestamps do not shuffle
Opaque cursorsClients cannot depend on internals; you can change them
Say whether more existhasMore or a next link, so clients know when to stop
Total counts are optionalCOUNT(*) on large tables is slow; offer it only if needed

The choice between offset and cursor paging is the next question.

51. What is the difference between offset-based and cursor-based pagination? ​

The short answer

Offset paging asks for "skip N rows, return the next M", ?page=3&limit=20: easy to build and lets users jump to any page, but the database still reads and throws away all skipped rows, so deep pages are slow, and items inserted or deleted meanwhile make pages skip or repeat rows. Cursor paging asks for "the next M rows after this position", using the last item's sort key: each page is fast at any depth and stable under changes, but you can only go forward or back, not jump to page 57.

offset: OFFSET 40 LIMIT 20rows 1 to 40: read, then thrown awayrows 41 to 60: returneda new order at the top shifts every row down by one: row 40 appears again on this pagecursor: WHERE (created_at, id) < (last seen) LIMIT 20skipped by the indexnext 20: returnedjumps straight to the position, any depth
Count your way there, or start where you left off. Offset paging reads and discards every earlier row, and shifts when rows are added. Cursor paging uses the last seen key to jump straight to the next rows.
OffsetCursor, also called keyset
Request?page=3&limit=20?cursor=…&limit=20
SQLOFFSET 40 LIMIT 20WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT 20
Deep pagesSlower and slowerConstant speed with an index
Inserts and deletes meanwhileRows skipped or repeatedStable
Jump to page NYesNo
Total pagesEasy, but costly to countUsually not offered
Use forSmall admin tables, "page 3 of 7" UIsFeeds, infinite scroll, APIs, syncing data

Building a cursor:

ts
const encode = (c: { createdAt: string; id: string }) => Buffer.from(JSON.stringify(c)).toString('base64url')
const decode = (s: string) => JSON.parse(Buffer.from(s, 'base64url').toString()) as { createdAt: string; id: string }

async function listOrders(customerId: string, limit: number, cursor?: string) {
  const after = cursor ? decode(cursor) : null
  const rows = await db.query(
    `SELECT id, created_at, total_pence FROM orders
     WHERE customer_id = $1 AND ($2::timestamptz IS NULL OR (created_at, id) < ($2, $3))
     ORDER BY created_at DESC, id DESC
     LIMIT $4`,
    [customerId, after?.createdAt ?? null, after?.id ?? null, limit + 1],          // (1)
  )
  const page = rows.slice(0, limit)
  const last = page.at(-1)
  return {
    data: page,
    nextCursor: rows.length > limit && last ? encode({ createdAt: last.created_at, id: last.id }) : null,   // (2)
  }
}
  1. Fetch one extra row to know whether another page exists, without counting.
  2. The cursor is the last row's sort key, encoded so clients treat it as an opaque token. An index on (customer_id, created_at, id) makes this fast at any depth.

52. How should an API support filtering and sorting? ​

The short answer

Use query parameters with a consistent, documented style, such as ?status=paid&createdAfter=2026-10-01&sort=-createdAt. Allow only an explicit list of fields to filter and sort by, validate every value, and map them to safe, parameterised database queries; never pass raw field names or values into SQL. Make sure the common filter and sort combinations are backed by indexes, and include the sort in the cursor when paging.

ts
const ListOrdersQuery = z.object({
  status: z.enum(['placed', 'paid', 'shipped', 'cancelled']).optional(),
  createdAfter: z.coerce.date().optional(),
  minTotal: z.coerce.number().int().nonnegative().optional(),
  sort: z.enum(['createdAt', '-createdAt', 'total', '-total']).default('-createdAt'),   // (1)
  limit: z.coerce.number().int().min(1).max(100).default(20),
})

const SORT_SQL = {                                                                      // (2)
  createdAt: 'created_at ASC, id ASC',
  '-createdAt': 'created_at DESC, id DESC',
  total: 'total_pence ASC, id ASC',
  '-total': 'total_pence DESC, id DESC',
} as const

app.get('/orders', async (req, res) => {
  const q = ListOrdersQuery.parse(req.query)
  res.json(await ordersRepo.list({ ...q, orderBy: SORT_SQL[q.sort] }))
})
  1. An allow-list of sort options, with - meaning descending, a common convention.
  2. Map each option to fixed SQL. User input never becomes part of the SQL text, which prevents injection through sort parameters.

Conventions you will see:

NeedCommon style
Equality?status=paid
Several values?status=paid,shipped or ?status=paid&status=shipped
Ranges?createdAfter=…&createdBefore=…, or ?total[gte]=1000
Search?q=earl+grey
Sort?sort=-createdAt,total

53. What are partial responses, and when are they useful? ​

The short answer

A partial response returns only the fields the client asks for, such as GET /products/tea?fields=id,name,pricePence, instead of the whole resource. It saves bandwidth and processing for clients that need a small part of a large object, such as a mobile list screen, and can avoid expensive joins for fields nobody asked for. The related idea, expansion, lets clients ask for related resources to be embedded, ?expand=customer, to avoid extra round trips. Use both sparingly, with allow-lists, because every combination must be supported and cached.

http
GET /products/tea-earl-grey?fields=id,name,pricePence
json
{ "id": "tea-earl-grey", "name": "Earl Grey", "pricePence": 450 }

Partial responses versus GraphQL: if many clients need very different shapes of the same data, GraphQL was designed for exactly that. A fields parameter suits a REST API with a few heavy resources.

Things to watch:

ConcernDetail
CachingEach fields combination is a different cache entry
AuthorisationField selection must never let clients read fields they could not see otherwise
ValidationOnly allow known field names

54. What are ETags, and how do they support conditional requests? ​

The short answer

An ETag, entity tag, is a short identifier for one version of a resource, sent by the server in the ETag response header, often a hash of the content or a version number. The client stores it and sends it back on later requests: with If-None-Match to ask "send it only if it changed", which lets the server answer 304 Not Modified with no body, and with If-Match to say "only apply my update if it is still this version", which prevents overwriting someone else's change.

clientAPI① GET /products/tea200, ETag: "v7", body② GET, If-None-Match: "v7"304 Not Modified, no body③ PATCH, If-Match: "v7"412 if it is now "v8"
A version stamp on every response. ① The first read returns the data and its ETag. ② Later reads send the ETag back; if nothing changed, the answer is a tiny 304. ③ An update sent with the ETag fails with 412 if someone changed the resource in the meantime.

Strong and weak ETags: a strong ETag, "v7", means byte-for-byte identical. A weak one, W/"v7", means equivalent in meaning, for example the same data with different whitespace or compression. Express generates weak ETags for res.send and res.json by default, by hashing the body.

Where the savings come from: with If-None-Match, a client polling a large catalogue every minute receives a few hundred bytes instead of the full response when nothing changed. The server still runs the handler unless it can check the version cheaply, such as reading an updated_at column, before building the body (question 55).

55. What are conditional HTTP requests, and how can they prevent unnecessary work? ​

The short answer

A conditional request includes a precondition header, so the server acts only if it holds. For reads, If-None-Match with an ETag, or If-Modified-Since with a date, lets the server reply 304 Not Modified without a body when the client's copy is current. For writes, If-Match or If-Unmodified-Since lets the server refuse an update with 412 Precondition Failed if the resource changed since the client read it. Checking a cheap version stamp before doing expensive work saves bandwidth, database load and lost updates.

ts
app.get('/catalogue', async (req, res) => {
  const version = await catalogue.currentVersion()                       // (1) a cheap query
  const etag = `"cat-${version}"`
  res.set('ETag', etag).set('Cache-Control', 'no-cache')                 // (2)
  if (req.get('If-None-Match') === etag) return res.status(304).end()    // (3)
  res.json(await catalogue.fullListing())                                // (4) expensive
})
  1. Read only the version, such as a counter bumped on every catalogue change.
  2. no-cache means "you may store this, but check with me before using it", which is exactly what conditional requests do.
  3. Unchanged: answer in a few bytes, skipping the expensive query entirely.
  4. Changed: build and send the full response.
HeaderSent by the clientServer's answer when the condition fails
If-None-Match: "v7"On reads304 Not Modified, when it still matches
If-Modified-Since: <date>On reads304, when not modified since
If-Match: "v7"On writes412 Precondition Failed, when it no longer matches
If-Unmodified-Since: <date>On writes412

56. How do you handle optimistic concurrency in an API? ​

The short answer

Optimistic concurrency assumes conflicts are rare: you let clients read and edit freely, and only check at save time whether someone else changed the record in between. Give every resource a version, such as a number incremented on each update or an ETag. The client sends the version it read with its update, in If-Match or in the body, and the database update includes WHERE version = $expected. If no row matched, someone else saved first, so the API returns 409 Conflict or 412 Precondition Failed, and the client reloads and tries again.

ts
app.patch('/products/:sku', requireRole('admin'), async (req, res) => {
  const expected = Number(req.get('If-Match')?.replaceAll('"', ''))            // (1)
  if (!Number.isInteger(expected)) return res.status(428).json({ type: 'if_match_required' })   // (2)

  const patch = ProductPatch.parse(req.body)
  const result = await db.query(
    `UPDATE products SET name = COALESCE($1, name), price_pence = COALESCE($2, price_pence),
            version = version + 1
     WHERE sku = $3 AND version = $4
     RETURNING *`,
    [patch.name ?? null, patch.pricePence ?? null, req.params.sku, expected],   // (3)
  )
  if (result.rowCount === 0) return res.status(412).json({ type: 'version_conflict' })   // (4)
  const updated = result.rows[0]
  res.set('ETag', `"${updated.version}"`).json(updated)                         // (5)
})
  1. The version the client last saw, sent as an ETag.
  2. 428 Precondition Required tells clients that unconditional updates are not allowed on this resource.
  3. Update only if the version still matches, and bump it in the same statement. The check and the write are one atomic operation.
  4. No row matched: someone else saved first. Nothing was overwritten.
  5. Return the new version, so the client can make its next change.

Why not lock the row while the user edits? A person may keep an edit form open for twenty minutes. Holding a database lock that long blocks everyone else. Optimistic concurrency holds no lock at all; it only detects a conflict at the end. Pessimistic locking, for short transactions, is covered in the databases module.

What the client should do on a conflict: reload the latest version, show the user what changed, and let them reapply their change, or merge automatically when the changed fields do not overlap.

57. What are common API versioning strategies? ​

The short answer

The common strategies are a version in the URL path, /v1/orders, which is the most visible and easiest to route and cache; a version in a header, either a custom one such as Api-Version: 2026-10-01 or a media type in Accept; and, less often, a query parameter. Whatever you choose, change versions rarely: make additive changes without a new version, introduce a new version only for breaking changes, announce deprecations with dates, and run old and new versions side by side until clients have moved.

StrategyExampleProsCons
URL path/v1/ordersObvious, easy to route, logs show itURLs change between versions
Custom headerApi-Version: 2Clean URLsHidden; harder to try in a browser
Date-based headerStripe-Version: 2026-10-01Fine-grained, per-client pinningMore work to maintain
Media typeAccept: application/vnd.shop.v2+jsonPurist RESTAwkward for most clients
Query parameter/orders?version=2SimpleEasy to forget, confuses caches

Changes that do not need a new version: adding an endpoint, adding an optional request field, adding a response field. Clients must be written to ignore fields they do not know.

Changes that do: removing or renaming a field, changing a field's type or meaning, making an optional field required, changing error formats or status codes.

Retiring a version, politely:

http
HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </v2/orders>; rel="successor-version"

The Deprecation and Sunset headers tell clients, and their monitoring, when the old version stops working. Also email registered developers, watch which clients still call the old version, and contact them before the date.

58. How do you document APIs with OpenAPI or Swagger? ​

The short answer

OpenAPI, formerly called Swagger, is a standard format, in YAML or JSON, for describing an HTTP API: its endpoints, parameters, request and response bodies, status codes, authentication and examples. From one OpenAPI document, tools generate interactive documentation such as Swagger UI or Redoc, client libraries in many languages, server stubs, request validation and mock servers. Keep the document generated from your code or schemas, or checked against them in CI, so it never drifts from what the API really does.

yaml
openapi: 3.1.0
info: { title: Shop API, version: 1.4.0 }
paths:
  /orders/{orderId}:
    get:
      summary: Get one order
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string, example: ord_42 } }
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: Not found
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  schemas:
    Order:
      type: object
      required: [id, status, totalPence]
      properties:
        id: { type: string }
        status: { type: string, enum: [placed, paid, shipped, cancelled] }
        totalPence: { type: integer, minimum: 0 }

Two ways to keep it accurate:

ApproachHowFits
Code firstGenerate OpenAPI from your validation schemas, such as Zod with zod-to-openapi, or framework decoratorsTeams that change code first
Design firstWrite the OpenAPI document, review it, then implement and validate against itPublic APIs, many teams agreeing a contract

Serving docs: a /docs route with Swagger UI or Redoc for internal APIs; a public developer portal for partner APIs. Check in CI that the published document matches the running API.

59. How do Postman collections help API development and testing? ​

The short answer

A Postman collection is a saved, shareable set of API requests, grouped into folders, with their URLs, headers, bodies and authentication, plus environments that switch variables such as the base URL and tokens between local, staging and production. It lets developers, testers and partners explore and call an API without writing code, shares working examples across a team, and can be imported from or exported to an OpenAPI document. Collections can also be run automatically from the command line with Newman.

FeatureWhat it gives you
Collections and foldersAll of an API's requests, organised
EnvironmentsVariables such as baseUrl and token switch between local, staging and production
Pre-request scriptsFetch a token before each request
Import from OpenAPIA ready-made collection from your spec (question 58)
SharingWorkspaces for a team or partners
Newman CLIRun a collection from a pipeline

A practical habit: ship a collection, or an equivalent file for tools such as Bruno or Insomnia, with every new API, so the first person to integrate starts from working requests instead of the documentation alone. Keep secrets out of shared collections; use environment variables that each person fills in.

60. What is API mocking, and when should it be used? ​

The short answer

API mocking means running a stand-in that answers like the real API, with realistic responses, before or instead of the real one. It lets front-end and back-end teams work in parallel once they agree the contract, lets you build against a partner's API that is not ready or is expensive to call, and lets you reproduce error cases such as timeouts or a 500 on demand. Mock servers can be generated from an OpenAPI document, so the mock follows the contract rather than someone's guess.

SituationMocking helps because
Front end waiting for the back endBuild screens against the agreed contract today
Third-party API with costs or rate limitsDevelop without real calls
Hard-to-trigger statesSimulate 429, 503, slow responses, empty lists
Demos and prototypesNo real data needed

Tools: Prism generates a mock server from an OpenAPI file; Mock Service Worker intercepts requests inside a browser or Node.js app during development; Postman offers hosted mock servers.

The risk: a mock that drifts from the real API hides integration problems until late. Generate mocks from the same contract the real API is checked against (question 58).

61. How do you design consistent API error responses? ​

The short answer

Use one error format for every endpoint, ideally the standard Problem Details format, RFC 9457, with content type application/problem+json. It has a type that identifies the kind of error and never changes, a human-readable title and detail, the HTTP status, and an instance for this occurrence, plus your own fields such as a list of invalid fields and a request ID. Pair it with the correct status code, keep messages safe for clients, and document every type.

json
{
  "type": "https://api.shop.example/problems/validation-error",
  "title": "Your request has invalid fields",
  "status": 400,
  "detail": "2 fields failed validation",
  "instance": "/orders",
  "requestId": "9f1c2e7a",
  "errors": [
    { "field": "items[0].qty", "message": "must be at least 1" },
    { "field": "deliveryDate", "message": "must be in the future" }
  ]
}
FieldPurpose
typeStable identifier clients can switch on; a URL to documentation
titleShort summary, the same for every occurrence of this type
statusThe HTTP status, repeated for convenience
detailWhat happened this time, safe for the client
instanceWhich request or resource
Extensionserrors, requestId, retryAfter, as needed

What makes error responses good for clients:

  1. Machine-readable first: code branches on type, never on the English text.
  2. Field-level details for validation, so a form can highlight the right input.
  3. A request ID, so support can find the logs (question 39).
  4. The same shape everywhere, produced by the central error handler (question 35).

62. How do you handle retries safely in API clients? ​

The short answer

Retry only failures that might succeed next time: timeouts, connection errors, 429, 502, 503 and 504, never 400, 401, 403, 404 or 422. Retry only operations that are safe to repeat: GET, PUT and DELETE, or POST requests sent with an idempotency key. Wait between attempts with exponential backoff and random jitter, respect Retry-After, cap the number of attempts and the total time, and set a timeout on every attempt. Unlimited, immediate retries turn a small outage into a big one.

ts
const RETRYABLE = new Set([408, 429, 500, 502, 503, 504])

async function callPaymentsApi(path: string, body: unknown, idempotencyKey: string) {
  for (let attempt = 0; attempt < 4; attempt++) {
    try {
      const res = await fetch(`${PAYMENTS_URL}${path}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },   // (1)
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(3_000),                                                    // (2)
      })
      if (res.ok) return res.json()
      if (!RETRYABLE.has(res.status) || attempt === 3) throw new HttpError(res.status, 'payments_failed', 'payment call failed')   // (3)
      const retryAfter = Number(res.headers.get('Retry-After'))
      await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt))                      // (4)
    } catch (err) {
      if (err instanceof HttpError || attempt === 3) throw err
      await sleep(backoff(attempt))                                                            // network error or timeout
    }
  }
}
const backoff = (attempt: number) => Math.random() * Math.min(5_000, 200 * 2 ** attempt)      // (5)
  1. The same idempotency key on every attempt, so a retried charge is not applied twice (question 46).
  2. A timeout per attempt, so one hung request does not hold the caller for ever.
  3. Give up immediately on errors retrying cannot fix.
  4. Respect Retry-After when the server says how long to wait.
  5. Exponential backoff with full jitter, so thousands of clients do not retry in lockstep (the retry implementation question).

At the system level, retries combine with timeouts and circuit breakers to keep one failing dependency from taking down everything that calls it; that is covered in the architecture module.

63. How do you secure and expose APIs to third-party partners? ​

The short answer

Give each partner its own identity and credentials, ideally OAuth 2.0 client credentials with short-lived tokens and narrow scopes, or for high-trust links mutual TLS; if you use API keys, store them hashed, scope them, and make rotation easy. Put the API behind a gateway that enforces authentication, per-partner rate limits and quotas, request size limits and logging. Expose only a deliberately designed, versioned subset of your API, sign webhooks you send them, provide a sandbox, and keep an audit trail of every call.

LayerControl
IdentityOne client per partner; OAuth client credentials, mTLS, or scoped API keys
AuthorisationScopes such as orders:read; tenant checks on every record
TrafficPer-partner rate limits, quotas, payload limits, at a gateway
NetworkTLS only; optional IP allow-lists for server-to-server links
ContractA stable, versioned, documented API; deprecation policy (question 57)
Webhooks to partnersSigned with HMAC and a timestamp, so they can verify and reject replays
OperationsA sandbox environment, audit logs, alerting on unusual usage

Webhook signatures, the part partners must verify:

ts
const timestamp = Math.floor(Date.now() / 1000).toString()
const signature = createHmac('sha256', partner.webhookSecret).update(`${timestamp}.${rawBody}`).digest('hex')
await fetch(partner.webhookUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Shop-Signature': `t=${timestamp},v1=${signature}` },
  body: rawBody,
})

Including the timestamp in the signed text lets the partner reject old messages replayed by an attacker. How they verify it is shown in the crypto question.

Why not reuse your internal API? Internal endpoints change often and trust callers more. A partner API is a promise you must keep for years, so design it as a separate product surface, with its own documentation, limits and support. Machine-to-machine OAuth is covered in the client credentials flow.

Combine chapters into one PDF

Pick the chapters you want. They print in the order you pick them.

Interview Prep
Express & REST APIs
Express
REST API design
Testing
Other topics
Nothing picked yet