Top REST API Design Interview Questions and Answers

REST API design interviews can turn on one small choice, like whether a retry creates a second order. These REST API design interview questions give you five common prompts, answer points, and follow-ups to rehearse aloud.

We analyzed 6 ranking pages on REST API interview questions and found that only 1 covers idempotency keys, cursor pagination, Problem Details errors, 409 Conflict and 429 together. Only 1 of 6 names 409 Conflict.

We analyzed 6 ranking pages (browserless.io, hipeople.io, turing.com, roadmap.sh, Indeed, educative.io) on REST API interview questions and found that only 1 covers idempotency keys, cursor pagination, Problem Details errors, 409 Conflict and 429 together. Only 1 of 6 names 409 Conflict.

Table of Contents

• How Would You Model a REST API for an Online Store?
• How Would You Add Pagination, Filtering, and Sorting?
• How Should a REST API Handle Retries and Idempotency?
• How Would You Design Consistent Errors and HTTP Status Codes?
• How Would You Version a REST API Without Breaking Existing Clients?
• Compare These REST API Design Questions at a Glance
• FAQ
• Conclusion

1. How Would You Model a REST API for an Online Store?

Start by naming the main resources, then show how clients act on them. A clear answer might use /products, /customers, and /orders. Use plural nouns for collections. Use an ID to address one item, such as /orders/847.

Then explain the HTTP methods. GET /products/42 reads a product. POST /orders creates an order. PUT /orders/847 replaces the order, while PATCH /orders/847 changes selected fields. DELETE removes a resource when the business rules allow it. The method says what happens; the URL says which resource is involved.

Nest a resource only when the parent relationship helps clients. /customers/123/orders makes sense because those are one customer’s orders. Avoid a long chain such as /customers/123/orders/847/items/3 when a flatter URL would be easier to use. A product can link to its reviews at /products/42/reviews.

Show that you understand REST beyond noun-based URLs. Each request should carry what the server needs, rather than relying on hidden session state. Responses can include links to related actions. That idea is called HATEOAS, though many APIs use only some REST constraints. A resource-oriented use of HTTP methods also means choosing methods for their defined semantics, not treating every request as a generic command.

A useful follow-up is: “Is POST /getUser RESTful?” Explain that the verb in the path and the generic POST action weaken the uniform interface. You can also discuss the trade-off: some teams use action-style endpoints when a business operation does not map cleanly to basic resource changes.

For a mock, practice taking one broad store prompt and turning it into a short chain of design decisions. How to Practice API Design Questions With Prompts lays out a way to reveal follow-ups only after you answer the first part.

2. How Would You Add Pagination, Filtering, and Sorting?

Put filters and sort rules in query parameters, and paginate every collection that could grow. For example, GET /products?category=books&sort=-price&limit=20 asks for a slice of products in a chosen order. Set a maximum page size so one request cannot ask the service to return an unbounded list.

For a small admin table with stable data, page numbers and offsets can be easy for people to understand. A request might use ?page=3&per_page=20. But offset pagination can do more work on later pages. It can also skip or repeat rows if items are added or removed while a client is paging through the list.

For a large or frequently changing feed, describe cursor pagination. The response returns a page plus an opaque token for the next request. The client sends that token back rather than calculating an offset. Keep the sort order stable by adding a unique tie-breaker, such as an ID, when several rows share the same timestamp.

Separate the three concerns in your answer. Filtering limits which records match. Sorting defines their order. Pagination controls how many records come back at once. If the client asks for a category and a price range, the API should apply both filters before returning the requested page.

Then cover the contract details. State the default sort order and page size. Say what happens when a filter is invalid. Explain whether the response includes a next-page token or links. Avoid promising a total count if computing it would be costly or if the client does not need it.

Interviewers may ask what happens when a collection grows or changes during an export. That is a good moment to explain why a cursor can keep a traversal steadier than an offset. The choice depends on how clients move through the data, not on a rule that every API must use one pagination style.

3. How Should a REST API Handle Retries and Idempotency?

Define idempotency by the result on the server: repeating the same request has the same effect as making it once. This matters when a client times out. The server may have completed the request even though the response never reached the client.

GET is safe to repeat because it reads data. PUT can be idempotent when it sets a resource to a specific state. DELETE is also idempotent in terms of final server state, even if a later response says the resource is already gone. POST often creates a new resource each time, so a retry may create a duplicate. PATCH depends on the operation: setting a field to a value can be idempotent, while incrementing a counter is not.

For a create or payment request that must tolerate retries, describe an idempotency-key pattern. The client sends a unique key for one logical operation. The server stores the key with the result, then returns that result when it receives the same key again. The key needs a defined scope and retention period, and the server should reject reuse with a different request body.

Be precise about what the key protects. It prevents duplicate processing for matching retries; it does not make every part of a distributed workflow happen exactly once. If a request triggers an email or a downstream job, those side effects need their own deduplication plan.

HTTP method semantics distinguish safe and idempotent behavior. In an interview, connect those semantics to the actual failure case: the client cannot tell from a timeout whether the server committed the order. Then explain how you would test that sending the same request twice leaves one order in the intended state.

4. How Would You Design Consistent Errors and HTTP Status Codes?

Use the HTTP status code to describe the outcome, then return a stable error body that helps the client respond. Avoid returning 200 OK for a failed request and hiding the failure in a JSON field. A client should not need to inspect a custom message to learn whether the request succeeded.

Use 201 Created when a request creates a resource, and include a Location header when clients need the new resource’s URL. Use 204 No Content when the request succeeds but the response has no body. For common failures, 400 can mean a malformed request, 401 missing or invalid authentication, 403 a caller without permission, and 404 a resource that cannot be found.

Keep the distinction between client and server errors clear. A validation issue should not look like an unexpected server failure. Use 409 Conflict when the request conflicts with the current resource state. Use 429 Too Many Requests when rate limits apply. An unexpected failure belongs in the 5xx family, not in a success response.

Choose one response shape for errors across endpoints. For example, provide a problem type, a short title, a status, and details the client can use to correct the request. Keep the human-facing message separate from any stable code used by software. Don’t expose stack traces or private data in an error body.

One option is Problem Details for HTTP APIs, a standard format for describing errors in a response. You can explain how your API would use the same fields consistently for invalid input, missing resources, and conflicts.

A strong follow-up answer covers security and support. Authenticate requests with a suitable token scheme, check authorization for the specific resource, and avoid placing secrets in URLs. Add rate limits where needed, and return enough safe context for a client to report an issue.

5. How Would You Version a REST API Without Breaking Existing Clients?

First, identify the change and the clients that rely on the current contract. Adding an optional field may be compatible with some clients, but changing a string into an object can break a parser. Older mobile apps or partner integrations may keep using the old response long after a web client updates.

URI versioning makes the contract easy to see, such as /v1/orders and /v2/orders. It is straightforward for clients to test and for infrastructure to route. Header or media-type versioning keeps the path stable, but clients must set the right header and teams need to account for that choice in routing and testing.

Don’t version every small addition by default. Prefer compatible changes when possible, such as adding an optional response field while preserving existing meanings. Treat removals, changed field types, or changed behavior as potential breaking changes. A new version can make that boundary explicit, but it also means supporting and migrating clients.

Describe a migration plan, not only a version format. Keep the old contract available while active clients move. Test old and new client behavior against the same domain states. Track which versions still receive traffic, communicate planned changes, and retire a version only when the service’s support policy allows it.

One useful follow-up is: “What if the new client rolls back after the server changes?” Explain how deployment order and compatibility affect that case. Phantom Code AI can help you rehearse the answer aloud during mock interview practice, then refine the trade-offs you explain.

Compare These REST API Design Questions at a Glance

Use this quick grid to pick a practice prompt based on the skill you want to show. A good answer makes a choice, explains its cost, then checks what could fail.

Other common follow-ups test your range. Be ready to explain JSON versus XML through the Accept and Content-Type headers. Explain how OAuth and JWT fit different parts of an authentication flow. You may also be asked about HATEOAS links, cache controls such as ETag, browser CORS rules, or rate limits.

For a broader design answer, mention OpenAPI as a way to write and share an API contract. Then say how you would test that contract, watch latency and error rates, and limit payload size where it helps. A gateway can handle shared concerns such as authentication or throttling, but it does not replace clear service-level rules.

FAQ

What are the most common REST API design interview questions?

Common REST API design questions ask how you model resources, choose HTTP methods, paginate collections, handle retries, and return errors. Interviewers also ask about versioning and authentication. Start with a clear design, then explain one trade-off and a failure case.

What is the difference between PUT and PATCH?

PUT generally replaces a resource at a known URL, while PATCH applies a partial change. Repeating a PUT with the same representation should leave the resource in the same state. PATCH may or may not be idempotent, depending on its instructions. For example, setting a quantity to five is different from adding five to the quantity.

How do you make a POST request safe to retry?

Use an idempotency key for one logical operation and have the server store the result tied to that key. If the client retries after a timeout with the same key and request, the server can return the saved result instead of creating another resource. Define what happens when a key is reused with different data, and test that duplicate side effects do not occur.

Should I use URL or header versioning for a REST API?

Either can work; choose based on how clients and your infrastructure handle version selection. A URL such as /v1/orders makes the version visible and is simple to test. A header keeps the path stable but requires clients and routing to honor that header. For either choice, plan how clients will move and how long old contracts will remain supported.

How should a REST API return validation errors?

Return an appropriate client-error status and a consistent body with details the caller can act on. Identify the field or rule that failed without exposing private data or internal stack traces. Keep machine-readable error codes stable, since clients may branch on them. A standard format such as Problem Details can help make errors consistent across endpoints.

Conclusion

Practice these prompts by answering aloud, then explain the trade-off behind each choice. For live mock practice, Phantom Code AI can provide real-time interview guidance; start with the store design question and work through its follow-ups.