REST API Design Interview Questions and Answers

Common strategies:

• URI path versioning: https://api.example.com/v1/orders. Most visible and easiest to route and cache, at the cost of polluting the URL.
• Query parameter: /orders?version=2. Easy but easy to forget and awkward to cache.
• Custom media type: Accept: application/vnd.example.v2+json. Purest REST approach but harder to test and document.
• Custom header: X-Api-Version: 2. Clean URLs, but invisible and frequently missed.

For a public API, URI versioning is the pragmatic default. More important than the mechanism is the policy: prefer additive, backward-compatible changes; never change the meaning of an existing field; announce deprecations early with Deprecation and Sunset headers; keep old versions running for a defined window; and protect consumers with contract tests in CI.

• POST creates a subordinate resource or triggers a non-idempotent action. The server assigns the identifier and returns 201 with a Location header.
• PUT replaces the entire resource at a known URI and is idempotent. Any omitted field is reset, which surprises clients doing partial updates.
• PATCH applies a partial modification and is generally not idempotent unless the patch document is written to be so.

PATCH /users/42
Content-Type: application/merge-patch+json

{ "email": "new@example.com" }

Two PATCH formats dominate: JSON Merge Patch (RFC 7396, simple) and JSON Patch (RFC 6902, a list of explicit operations). Prefer PUT when the client owns the full representation, PATCH when it does not. A frequent pitfall is using PUT with a partial body, which silently wipes unspecified fields.

Two main approaches:

• Offset pagination: GET /items?limit=20&offset=40. Simple and allows jumping to a page, but degrades as offsets grow because the database must scan and discard rows, and results shift when items are inserted or deleted.
• Cursor (keyset) pagination: GET /items?limit=20&after=eyJpZCI6MTIzfQ. The cursor encodes the last seen sort key, so the query uses an indexed range scan and stays stable under concurrent writes.

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

Use cursor pagination for feeds and large, changing datasets; offset only for small admin tables. Always cap the limit, return a next link or cursor, avoid exposing raw IDs when they leak information, and document the sort order because cursors are only valid for it.

Group them by intent and be consistent:

• 2xx success: 200 OK, 201 Created (with Location), 202 Accepted for async work, 204 No Content after DELETE.
• 3xx: 301/308 for permanent redirects, 304 Not Modified for conditional GET.
• 4xx client errors: 400 malformed syntax, 401 unauthenticated, 403 forbidden, 404 not found, 405 wrong method, 409 conflict, 412 precondition failed, 415 unsupported media type, 422 semantic validation failure, 429 rate limited.
• 5xx server errors: 500 unexpected failure, 502 bad gateway, 503 unavailable (include Retry-After), 504 gateway timeout.

Do not return 200 with an error body: it breaks monitoring, retries and generic clients. Reserve 5xx for genuine server faults so alerts stay meaningful. Pick 400 for malformed requests but 422 for well-formed input that fails business validation, and document your mapping.

The client generates a unique key per logical operation and sends it in a header, typically Idempotency-Key.

POST /payments
Idempotency-Key: 4d7c2e6a-2b1f-4f9a-9c3d-1a2b3c4d5e6f

{ "amount": 5000, "currency": "USD" }

The server stores the key together with the request fingerprint and the final response (or a "processing" marker). On a retry with the same key it returns the stored response instead of charging again. Use a unique constraint on the key to make concurrent duplicates safe: one request wins and others receive 409 while the first is in flight.

Keys should expire after a sensible window, be scoped per account, and detect mismatched payloads by comparing a hash. This pattern is essential for payments, order creation and any non-idempotent POST that clients or gateways may retry.

Use one consistent, machine-readable shape. A widely adopted choice is RFC 7807 application/problem+json:

{
  "type": "https://example.com/problems/insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "Account balance is 10 USD, required 50 USD.",
  "instance": "/payments/abc",
  "errors": [
    { "field": "amount", "code": "above_balance" }
  ]
}

Key properties: a stable type or code clients can branch on, a human-readable message, the HTTP status mirrored in the body, and field-level details for validation errors. Never leak stack traces, SQL or internal hostnames. Include a correlation or request id so support can trace the failure in logs.

Design the error contract once and reuse it across every endpoint; inconsistent error shapes are one of the most common sources of brittle client code.

Expose them as query parameters with a clear convention:

GET /articles?status=published&author=42&sort=-created_at&fields=id,title

• Filtering: one parameter per field, or a documented DSL for ranges (price[gte]=10). Only allow filtering on indexed, allow-listed columns to avoid full scans.
• Sorting: a sort parameter with comma-separated fields where a leading - means descending. Whitelist sortable columns because the value may reach an ORDER BY.
• Sparse fieldsets: a fields parameter to trim payload size, useful for mobile clients and bandwidth-sensitive integrations.

Never interpolate user input directly into SQL; map names to known columns. Cap the number of filters and sort keys, and cache the allowed combinations. These parameters compose naturally with pagination and projection, and are usually preferable to building bespoke endpoints for every view.