In this article
Foundations
What is a REST API?
A REST API is a web interface that exposes resources, such as orders or customers, at addresses and lets clients act on them with the standard HTTP (Hypertext Transfer Protocol) methods. REST means representational state transfer, an architectural style that Roy Fielding described in his 2000 doctoral dissertation. It is a set of constraints on how client and server communicate, not a protocol. Many published APIs called REST apply only some of the constraints.
Why it is asked: it checks that you can separate the style from the habit of sending JavaScript Object Notation (JSON) over HTTP. Read the full explanation: system design.
What are the constraints that make an API RESTful?
Fielding's chapter 5 lists six: client-server separation, statelessness, cacheability, a uniform interface, a layered system and, optionally, code on demand. He defines the uniform interface by four sub-constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, and hypermedia as the engine of application state (Fielding, 2000, section 5.1). The dissertation calls the uniform interface the central feature that distinguishes REST.
Why it is asked: strong candidates can name more than "stateless and uses HTTP". Read the full explanation: system design.
What does stateless mean, and what does it cost?
Stateless means each request carries everything the server needs to understand it, and the server keeps no session context between requests. Fielding says this removes the need to retain application state between requests and lets an intermediary understand a request in isolation. The cost is repetitive data in each request and less server control over application behavior (Fielding, 2000). Credentials, not a server-side login session, travel with every call.
Why it is asked: it links one constraint to scaling and to a real cost. Read the full explanation: system design.
How should you name resources and design URIs?
Name a resource with a plural noun and let the HTTP method carry the verb: /orders and /orders/99, not /create-order. Microsoft's guidance recommends collection and item paths such as /customers/5/orders and advises avoiding uniform resource identifiers (URIs) more complex than collection, item, collection, because deeper nesting becomes hard to maintain (Azure Architecture Center, March 2025). Expose a deeper relationship as a link or a filter instead.
Why it is asked: naming shows whether you think in resources or in remote procedures. Read the full explanation: API design interview questions.
What are the Richardson maturity levels, and where does HATEOAS fit?
Leonard Richardson's 2008 model has four levels. Level 0 sends every operation as a POST to one address, level 1 gives each resource its own address, level 2 uses HTTP methods for operations, and level 3 adds hypermedia, meaning responses carry links to related resources and next actions. HATEOAS (hypermedia as the engine of application state) is level 3. Microsoft notes that many published APIs sit at about level 2 and that no general standard models HATEOAS (Azure Architecture Center).
Why it is asked: it tests whether you can describe real APIs without claiming purity. Read the full explanation: system design.
Methods and idempotency
What is the difference between GET and POST, and what does safe mean?
A safe method is one whose defined semantics are essentially read-only: the client neither requests nor expects a state change. RFC (Request for Comments) 9110 defines GET, HEAD, OPTIONS and TRACE as safe. POST asks the target resource to process the enclosed representation by its own rules, for example to create a resource, so it is neither safe nor idempotent (RFC 9110, sections 9.2 and 9.3.3). Never use GET for an action that changes data.
Why it is asked: crawlers and prefetchers assume GET is harmless. Read the full explanation: API design interview questions.
What does idempotent mean, and which methods are idempotent?
A method is idempotent when the intended effect of several identical requests equals the effect of one. RFC 9110 lists PUT, DELETE and the safe methods as idempotent. The server may still log each request, and the response can differ between attempts. The practical payoff is retries: a client may repeat an idempotent request automatically after a dropped connection, but should not automatically retry a non-idempotent one (RFC 9110, section 9.2.2).
Why it is asked: it is the property behind safe retries. Read the full explanation: system design.
Text description of the diagram
- GET is safe and idempotent.
- PUT and DELETE are idempotent but not safe.
- POST and PATCH are neither safe nor idempotent by definition.
When do you use PUT, and when POST, to create a resource?
Use PUT when the client knows the address and wants to create or replace the state there; use POST when the server chooses the address. RFC 9110 says PUT creates or replaces the target's state, answers 201 (Created) if it made one, and 200 or 204 if it modified an existing one. A successful POST that creates a resource should return 201 with a Location header naming it (RFC 9110, sections 9.3.3 and 9.3.4).
Why it is asked: it separates client-chosen from server-chosen identifiers. Read the full explanation: system design.
What is the difference between PUT and PATCH?
PUT replaces the whole resource state with the enclosed representation; PATCH applies a partial modification. RFC 5789 introduced PATCH because PUT only allows complete replacement, and says PATCH is neither safe nor idempotent by definition, though it can be written to be idempotent. The server must apply the whole patch atomically or none of it. JSON Merge Patch is one patch format, where a null value deletes a member (RFC 7396).
Why it is asked: partial updates are where retries and lost updates bite. Read the full explanation: API design interview questions.
Is DELETE idempotent, and what does a second delete return?
Yes, DELETE is idempotent: after the first successful call the resource is gone, and repeating it leaves the server in the same state. A second DELETE usually gets 404 (Not Found) because the resource no longer exists, as Microsoft's guidance lists for a DELETE on a missing resource (Azure Architecture Center); the response differs but the effect does not. A successful first DELETE returns 202 if the action is not yet enacted, 204 if it is done with nothing to say, or 200 with a description (RFC 9110, sections 9.2.2 and 9.3.5).
Why it is asked: it tests the difference between effect and response. Read the full explanation: system design.
How do you make a POST request safe to retry?
Have the client send a unique idempotency key with the request, and have the server store the result under that key and return the saved result on a repeat. Stripe's API works this way as of October 2026: an Idempotency-Key header of up to 255 characters, saved results for API v1, keys pruned after at least 24 hours, and an error if a repeat uses different parameters (Stripe API reference).
Why it is asked: payments and order creation cannot tolerate duplicates. Read the full explanation: system design.
Knowing it is half the job. Saying it is the other half.
Interview Clozo is an AI interview copilot for real interview rounds: it hears the question and puts a strong answer on your screen, and you say it in your own words. See the features or how it works.
Start Free Trial →Status codes and errors
Which success status code should you return: 200, 201, 202 or 204?
Return 200 with a representation for a normal success, 201 with a Location header when a resource was created, 204 when the action succeeded and there is nothing to send, and 202 when the work was accepted but is not finished. RFC 9110 defines 204 as success with no additional content, and Microsoft advises 202 for slow operations, with the status endpoint's address in the Location header (RFC 9110, Azure Architecture Center).
Why it is asked: precise codes show you read the protocol instead of returning 200 for everything. Read the full explanation: API design interview questions.
When do you return 400, 409 or 422?
Return 400 when the request is malformed, 422 when the syntax and content type are fine but the content cannot be processed, and 409 when the request conflicts with the current state of the resource. RFC 9110 defines 422 (Unprocessable Content) for well-formed but semantically wrong content, and 409 as a conflict the client may be able to resolve and resubmit, most likely on a PUT against a versioned resource (RFC 9110, sections 15.5.10 and 15.5.21).
Why it is asked: the three codes are easy to blur. Read the full explanation: system design.
What is the difference between 401 and 403?
401 means the request lacks valid authentication credentials; 403 means the server understood the request and refuses it. RFC 9110 requires a 401 response to carry a WWW-Authenticate header with a challenge. For 403 the client should not repeat the request with the same credentials. A server that wants to hide that a forbidden resource exists may answer 404 instead (RFC 9110, sections 15.5.2 and 15.5.4).
Why it is asked: it separates who you are from what you may do. Read the full explanation: system design.
How should an API format its error responses?
Use one machine-readable shape for every error. RFC 9457 defines problem details, served as application/problem+json, with the members type (a URI naming the problem), title, status, detail and instance. The status member is advisory, since the HTTP status code is the authority, and type defaults to about:blank when omitted. It obsoleted RFC 7807 in July 2023 (RFC 9457).
Why it is asked: consistent errors are what client developers feel first. Read the full explanation: API design interview questions.
How do you rate limit a REST API?
Count requests per client in a time window and answer 429 (Too Many Requests) when a client exceeds the limit. RFC 6585 adds the code, says the response should include an explanation in the body and may include a Retry-After header, and leaves open how the server identifies clients: by credentials, a cookie or something else. A 429 response must not be stored by a cache (RFC 6585, section 4).
Why it is asked: it moves from status codes to protecting a service. Read the full explanation: designing a distributed rate limiter.
Scale, change and documentation
Offset or cursor pagination: which would you choose?
Choose cursor pagination for data that changes while it is read, and offset pagination only for small, stable collections. Microsoft shows limit and offset parameters. Google's API Improvement Proposal 158 uses a page_size and an opaque page_token, with an empty next_page_token as the only end signal (Google API Improvement Proposal 158). In a ten-item example, one insert between two page requests made offset paging return item 8 twice, while the cursor returned each of the original ten items once.1
Why it is asked: it tests whether you think about data changing under the reader. Read the full explanation: system design.
How do you version a REST API?
There are four common approaches: put the version in the URI, in a query string, in a custom header, or in the media type. Microsoft's guidance says URI and query-string versioning are cache-friendly because one address always means the same data, while header and media-type versioning need more logic and can duplicate cached data. (Azure Architecture Center). Add pagination from the start too: Google's proposal 158 says adding it later is backwards-incompatible (API Improvement Proposal 158).
Why it is asked: every API changes, and the question asks how you cope. Read the full explanation: system design.
What are ETags and conditional requests used for?
An ETag (entity tag) is an opaque validator the server sends to identify one version of a representation. A client sends it back in If-None-Match to avoid re-downloading unchanged data, and the server answers 304 (Not Modified). In If-Match on PUT, PATCH or DELETE, it stops a write when someone else changed the resource first, returning 412 (Precondition Failed). RFC 9110 names this the "lost update" problem (RFC 9110, section 13.1.1).
Why it is asked: it covers caching and concurrent writes with one mechanism. Read the full explanation: designing a distributed cache.
How do you handle a request that takes a long time?
Return 202 (Accepted) immediately and let the client poll. Microsoft's guidance says a slow POST, PUT, PATCH or DELETE can be made asynchronous: respond 202, put the address of a status endpoint in the Location header, and let the client check it until the work finishes. This keeps the connection short and avoids client timeouts on work that may take minutes (Azure Architecture Center).
Why it is asked: it tests designing around time instead of around one call. Read the full explanation: API design interview questions.
How do you document and test a REST API?
Describe it in an OpenAPI document, a machine-readable description of the API's surface and semantics, then generate reference pages, client libraries and contract tests from it. The OpenAPI Specification's latest version shown in October 2026 is 3.2.1. The latest version is linked from the OpenAPI Specification, and Microsoft's guidance says the specification began as Swagger and was renamed when the OpenAPI Initiative took it over (Azure Architecture Center).
Why it is asked: a design that cannot be described cannot be reviewed. Read the full explanation: API design interview questions.
For how these questions fit into a full interview process, see the interview loops guide and the system design interview framework.
Follow-up questions
What is the difference between REST and RESTful?
REST is the architectural style; RESTful is an adjective for an API that follows it. Because the style has several constraints, an API is better described by which constraints it meets; the Richardson levels grade one of them, the uniform interface: resources, then methods, then hypermedia.
How do you prepare for a REST API interview?
Practise saying the method, status-code and idempotency rules in one breath, then design a small API such as orders aloud and defend each choice. Prepare one example each for pagination, errors and retries.
Should a REST API use GraphQL or gRPC instead?
It depends on the clients and the traffic. Name the trade-off: REST gives cacheable, uniform resources over plain HTTP, and the alternatives trade that uniformity for flexible queries or compact binary calls.
- REST is a set of constraints, not a protocol; the uniform interface is its distinguishing feature.
- GET is safe and idempotent; PUT and DELETE are idempotent; POST and PATCH need an idempotency key or a condition to retry.
- Pick status codes by cause: 401 for missing or invalid credentials, 403 for refusal, 409 for state conflicts, 422 for unprocessable content.
- Use cursor paging for changing data and ETags with If-Match to stop lost updates.
- Describe the API in OpenAPI and return errors in one problem-details shape.
Sources
- RFC 9110: HTTP Semantics — IETF (Fielding, Nottingham, Reschke; June 2022), 1 Jun 2022
- RFC 5789: PATCH Method for HTTP — IETF (Dusseault, Snell; March 2010), 1 Mar 2010
- RFC 7396: JSON Merge Patch — IETF (Hoffman, Snell; October 2014), 1 Oct 2014
- RFC 9457: Problem Details for HTTP APIs — IETF (July 2023), 1 Jul 2023
- RFC 6585: Additional HTTP Status Codes — IETF (April 2012), 1 Apr 2012
- Architectural Styles and the Design of Network-based Software Architectures, chapter 5 (REST) — Roy Thomas Fielding, University of California, Irvine (doctoral dissertation, 2000), 1 Jan 2000
- Web API design best practices (Azure Architecture Center) — Microsoft Learn (ms.date 2025-03-27, read 2026-10-24), 27 Mar 2025
- Idempotent requests (Stripe API reference) — Stripe (undated page, read 2026-10-24), 24 Oct 2026
- AIP-158: Pagination — Google API Improvement Proposals (updated 2019-02-18), 18 Feb 2019
- OpenAPI Specification (latest) — OpenAPI Initiative (version 3.2.1 shown, read 2026-10-24), 10 Sep 2026
