Appearance
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=eyJjIjoiMjAyNi0xMC0yN1QxMDowMDowMFoiLCJpZCI6Im9yZF80MiJ9json
{
"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:
| Rule | Why |
|---|---|
| Default limit, maximum limit | ?limit=1000000 must not take down the database |
| Stable sort with a tie-breaker | ORDER BY created_at DESC, id DESC: equal timestamps do not shuffle |
| Opaque cursors | Clients cannot depend on internals; you can change them |
| Say whether more exist | hasMore or a next link, so clients know when to stop |
| Total counts are optional | COUNT(*) 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 | Cursor, also called keyset | |
|---|---|---|
| Request | ?page=3&limit=20 | ?cursor=…&limit=20 |
| SQL | OFFSET 40 LIMIT 20 | WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT 20 |
| Deep pages | Slower and slower | Constant speed with an index |
| Inserts and deletes meanwhile | Rows skipped or repeated | Stable |
| Jump to page N | Yes | No |
| Total pages | Easy, but costly to count | Usually not offered |
| Use for | Small admin tables, "page 3 of 7" UIs | Feeds, 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)
}
}- Fetch one extra row to know whether another page exists, without counting.
- 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] }))
})- An allow-list of sort options, with
-meaning descending, a common convention. - 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:
| Need | Common 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,pricePencejson
{ "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:
| Concern | Detail |
|---|---|
| Caching | Each fields combination is a different cache entry |
| Authorisation | Field selection must never let clients read fields they could not see otherwise |
| Validation | Only 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.
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
})- Read only the version, such as a counter bumped on every catalogue change.
no-cachemeans "you may store this, but check with me before using it", which is exactly what conditional requests do.- Unchanged: answer in a few bytes, skipping the expensive query entirely.
- Changed: build and send the full response.
| Header | Sent by the client | Server's answer when the condition fails |
|---|---|---|
If-None-Match: "v7" | On reads | 304 Not Modified, when it still matches |
If-Modified-Since: <date> | On reads | 304, when not modified since |
If-Match: "v7" | On writes | 412 Precondition Failed, when it no longer matches |
If-Unmodified-Since: <date> | On writes | 412 |
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)
})- The version the client last saw, sent as an ETag.
428 Precondition Requiredtells clients that unconditional updates are not allowed on this resource.- Update only if the version still matches, and bump it in the same statement. The check and the write are one atomic operation.
- No row matched: someone else saved first. Nothing was overwritten.
- 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.
| Strategy | Example | Pros | Cons |
|---|---|---|---|
| URL path | /v1/orders | Obvious, easy to route, logs show it | URLs change between versions |
| Custom header | Api-Version: 2 | Clean URLs | Hidden; harder to try in a browser |
| Date-based header | Stripe-Version: 2026-10-01 | Fine-grained, per-client pinning | More work to maintain |
| Media type | Accept: application/vnd.shop.v2+json | Purist REST | Awkward for most clients |
| Query parameter | /orders?version=2 | Simple | Easy 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:
| Approach | How | Fits |
|---|---|---|
| Code first | Generate OpenAPI from your validation schemas, such as Zod with zod-to-openapi, or framework decorators | Teams that change code first |
| Design first | Write the OpenAPI document, review it, then implement and validate against it | Public 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.
| Feature | What it gives you |
|---|---|
| Collections and folders | All of an API's requests, organised |
| Environments | Variables such as baseUrl and token switch between local, staging and production |
| Pre-request scripts | Fetch a token before each request |
| Import from OpenAPI | A ready-made collection from your spec (question 58) |
| Sharing | Workspaces for a team or partners |
| Newman CLI | Run 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.
| Situation | Mocking helps because |
|---|---|
| Front end waiting for the back end | Build screens against the agreed contract today |
| Third-party API with costs or rate limits | Develop without real calls |
| Hard-to-trigger states | Simulate 429, 503, slow responses, empty lists |
| Demos and prototypes | No 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" }
]
}| Field | Purpose |
|---|---|
type | Stable identifier clients can switch on; a URL to documentation |
title | Short summary, the same for every occurrence of this type |
status | The HTTP status, repeated for convenience |
detail | What happened this time, safe for the client |
instance | Which request or resource |
| Extensions | errors, requestId, retryAfter, as needed |
What makes error responses good for clients:
- Machine-readable first: code branches on
type, never on the English text. - Field-level details for validation, so a form can highlight the right input.
- A request ID, so support can find the logs (question 39).
- 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)- The same idempotency key on every attempt, so a retried charge is not applied twice (question 46).
- A timeout per attempt, so one hung request does not hold the caller for ever.
- Give up immediately on errors retrying cannot fix.
- Respect
Retry-Afterwhen the server says how long to wait. - 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.
| Layer | Control |
|---|---|
| Identity | One client per partner; OAuth client credentials, mTLS, or scoped API keys |
| Authorisation | Scopes such as orders:read; tenant checks on every record |
| Traffic | Per-partner rate limits, quotas, payload limits, at a gateway |
| Network | TLS only; optional IP allow-lists for server-to-server links |
| Contract | A stable, versioned, documented API; deprecation policy (question 57) |
| Webhooks to partners | Signed with HMAC and a timestamp, so they can verify and reject replays |
| Operations | A 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.