REST API design interview questions and answers for 2026

REST API design questions test whether you understand HTTP itself, not a particular framework. This guide gives you clear answers on methods, status codes, idempotency, pagination, versioning, error formats and concurrency control, so you can design an endpoint on a whiteboard and defend every choice.

The answers are based on the HTTP standards that define these rules (RFC 9110 for HTTP semantics, RFC 9457 for problem details and RFC 5789 for PATCH) and on MDN's HTTP reference. The pagination and conditional-update behaviour shown below was run against a small Node.js 24 server.

Beginner questions: resources, methods and status codes

1. What makes an API "RESTful"?

REST is an architectural style: clients work with resources identified by URLs, through a uniform interface (the standard HTTP methods), with stateless requests that each carry everything the server needs, such as an authentication token. Responses declare whether they can be cached. In practice, "RESTful" means using URLs for nouns, methods for actions and status codes for outcomes, consistently.

2. How do you name endpoints?

Use plural nouns and hierarchy where it reflects ownership, and let the method express the action:

Avoid verbs such as /getOrders or /deleteOrder. For operations that are not simple CRUD, a sub-resource such as POST /orders/42/cancellation keeps the model clear.

3. What is the difference between PUT and PATCH?

PUT replaces the whole resource with the representation you send; fields you omit are removed or reset. PATCH sends a set of changes. PUT is idempotent; PATCH is not guaranteed to be, because a patch such as "increment the counter" gives a different result each time. JSON Merge Patch (application/merge-patch+json, RFC 7396) is the simplest patch format for JSON APIs.

4. What do "safe" and "idempotent" mean?

A safe method is read-only from the client's point of view: GET, HEAD, OPTIONS and TRACE. An idempotent method has the same intended effect whether it is sent once or several times: all safe methods plus PUT and DELETE. POST and PATCH are not guaranteed to be idempotent. This matters because clients and proxies may retry idempotent requests automatically after a network failure.

5. Which status codes should every API use correctly?

• 200 OK, 201 Created (with a Location header), 202 Accepted (work queued, not done), 204 No Content.
• 400 malformed request, 404 not found, 405 method not allowed, 415 unsupported media type.
• 409 Conflict with the current state (a duplicate, an invalid state transition).
• 422 Unprocessable Content: well-formed but semantically invalid, which many APIs use for validation errors (others use 400; pick one and document it).
• 429 Too Many Requests, ideally with Retry-After; 500 for unexpected server errors; 503 when temporarily unavailable.

6. What is the difference between 401 and 403?

401 means the request is not authenticated: no credentials, or invalid or expired ones. The response carries a WWW-Authenticate header saying how to authenticate. 403 means the server knows who you are, but you are not allowed to do this. Some APIs return 404 instead of 403 to avoid revealing that a resource exists, which is a reasonable choice for private resources.

Intermediate questions: designing for real clients

7. How do you return errors?

Use one consistent, machine-readable format. RFC 9457, "Problem Details for HTTP APIs", which obsoletes RFC 7807, defines application/problem+json with the members type, title, status, detail and instance, and lets you add your own, such as field errors:

{
  "type": "https://api.example.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "2 fields are invalid",
  "errors": [
    { "field": "email", "message": "must be a valid email address" },
    { "field": "quantity", "message": "must be at least 1" }
  ]
}

Never leak stack traces or SQL in error bodies; log them server-side with a request id and return the id instead.

8. Offset or cursor pagination?

Offset pagination (?page=3&pageSize=20) is simple and supports jumping to a page, but it gets slower on large tables and can skip or repeat rows when data changes between requests. Cursor (keyset) pagination returns an opaque nextCursor that encodes the last item's sort key; the next query asks for rows after it, which stays fast with an index and stable under inserts. Always cap the page size on the server.

GET /items?limit=3
200 {"data":[1,2,3],"nextCursor":"eyJpZCI6M30"}

GET /items?limit=3&cursor=eyJpZCI6M30
200 {"data":[4,5,6],"nextCursor":"eyJpZCI6Nn0"}

9. How do you support filtering and sorting safely?

Use query parameters such as ?status=shipped&sort=-createdAt. Validate them against an allowlist of fields and directions, and never pass a client-supplied field name straight into SQL. Reject unknown parameters with a 400 rather than silently ignoring them, so client bugs surface early.

10. How do you version an API?

The most common approach is a major version in the path (/v1/orders), which is visible and easy to route; alternatives are a custom header or a media-type parameter. More important than the mechanism is the policy: add fields and endpoints without a new version, reserve a new major version for breaking changes, announce deprecations early, and run old and new versions side by side for a published period.

11. How do you prevent two users overwriting each other's changes?

Optimistic concurrency with conditional requests. The server returns an ETag for the resource; the client sends it back in If-Match when updating. If the resource changed in the meantime, the server responds 412 Precondition Failed; if the client sent no precondition and the server requires one, 428 Precondition Required.

PATCH /items/2                 -> 428 Precondition Required
PATCH /items/2  If-Match: "1"  -> 200 OK, ETag: "2"
PATCH /items/2  If-Match: "1"  -> 412 Precondition Failed

Advanced questions: reliability, security and scale

12. How do you make POST safe to retry?

Accept an idempotency key: the client generates a unique key per logical operation and sends it in an Idempotency-Key header. The server stores the key with the result, and a retry with the same key returns the stored result instead of creating a second order or charge. Payment APIs such as Stripe popularised the pattern; the header itself is still an IETF Internet-Draft rather than a published standard. Store keys with an expiry and scope them per client.

13. How do you handle long-running operations?

Do not hold the request open. Return 202 Accepted with a link to a status resource (Location: /jobs/981), let clients poll it or receive a webhook, and expose the final result when the job completes. This keeps timeouts and retries predictable.

14. How do you secure a REST API?

• HTTPS only, and authentication with short-lived tokens or secure session cookies.
• Authorisation on every request at object level: check that this user may access this order, not just "orders". Broken object level authorisation is ranked first (API1) in the OWASP API Security Top 10 2023.
• Validate every input against an allowlist; limit body sizes, page sizes and rates.
• Return only the fields the client needs, so internal fields never leak.
• Configure CORS narrowly for browser clients and log security-relevant events with request ids.

15. How do you use HTTP caching in an API?

Set Cache-Control deliberately (private, max-age, no-store for sensitive data) and provide validators. With an ETag, a client can send If-None-Match and get a 304 Not Modified with no body when nothing changed, saving bandwidth. Personalised responses must not be cached by shared caches.

16. When would you not choose REST?

GraphQL suits clients that need flexible, nested reads across many resources from one endpoint; gRPC suits low-latency service-to-service calls with strict schemas; WebSockets or server-sent events suit real-time pushes. A balanced answer says REST remains the default for public and CRUD-style APIs because it maps directly onto HTTP caching, tooling and monitoring.

17. How do you document and test an API?

Describe it with an OpenAPI document kept in the repository, generate reference docs and client types from it, and check in CI that the implementation still matches. Test contract cases (status codes, error bodies, pagination limits, permission failures) as well as the happy path. Tools such as Postman help explore and share request collections.

18. How should an API represent dates, money and identifiers?

Dates and times as ISO 8601 / RFC 3339 strings in UTC with an explicit offset (2026-10-09T08:30:00Z), never as local times without a zone. Money as an integer amount in the smallest currency unit plus a currency code ({"amount": 129900, "currency": "INR"}), or as a decimal string, never as a floating-point number. Identifiers as strings, even when they are numeric internally, so clients never lose precision on large values and you can change the format later.

What interviewers look for

• HTTP fluency: correct methods, status codes and headers, said precisely.
• Client empathy: consistent errors, predictable pagination, documented versioning.
• Reliability thinking: idempotency, retries, concurrency control, async jobs.
• Security by default: object-level authorisation, validation and limits.

How to practise

1. Design the endpoints for a small online shop on paper: products, carts, orders and refunds.
2. For each endpoint, write the success status, two failure statuses and the error body.
3. Implement one list endpoint with cursor pagination and one update endpoint with If-Match, then test both with curl.
4. Explain how a client should retry each request after a timeout.