REST API Interview Questions: Talk Through Design Decisions

REST API interview questions are rarely a vocabulary test. The interviewer already knows you can say the words "stateless" and "idempotent". What they are listening for is how you decide when two good options conflict, and whether you can explain that decision while someone watches. This article gives you a repeatable way to handle the REST API interview questions that come up most: resources and URLs, HTTP methods and status codes, idempotency and retries, pagination, versioning, error contracts, and auth at a conceptual level.

Why REST API Questions Reward Reasoning, Not Definitions

A memorised definition answers the first question and then stalls. A reasoning answer keeps the conversation going, which is what an interview is.

The pattern behind most questions

Almost every REST API question is really asking: given a constraint, what is your default, what does it cost you, and when would you change your mind? Say all four parts and you have answered the question and invited the next one.

1. Constraint — what is actually true here? (Mobile clients on flaky networks, a partner integration, a table with hundreds of millions of rows.)
2. Default — what you would normally do, stated plainly.
3. Trade-off — what that default costs you.
4. Change condition — the signal that would make you pick differently.

A short worked example

"Should this endpoint be PUT or PATCH?"

"The constraint is that clients edit one field of a large record. My default is PATCH with a partial body, because sending the whole resource back risks overwriting a field another client changed in between. The trade-off is that PATCH is not naturally idempotent, so a retried request can apply an edit twice. I would change my mind and use PUT if the client genuinely owns the whole representation and can send it in full — then retries are safe by definition."

That is roughly twenty seconds. It names a decision, not a dictionary entry.

Keep it to two or three sentences, then pause

Interviewers often have a follow-up queued. If you keep talking, you may answer a question they did not ask and bury the one they did. Land your answer, then stop. A short silence is not failure; it is an invitation.

Resources and URLs: Modelling the Domain Before the Endpoint

Start from nouns and relationships, not from your screens or your database tables. Tables are an implementation detail; screens are a UI concern. The API should describe the domain.

• Plural nouns for collections: /orders, /orders/{id}. Plural reads consistently whether you are addressing one item or many.
• Nest only where ownership is real: /orders/{id}/items is defensible because an item does not exist without its order. Nesting three levels deep usually means you have a resource hiding in plain sight.
• Promote a sub-resource when it has its own identity and lifecycle: if items can be moved between orders, queried independently, or have their own permissions, /items?orderId=... or /items/{id} is the honest model.

A common follow-up: "What if two clients need different shapes of the same resource?" The answer is representation, not a new URL. Use content negotiation, a query parameter such as ?fields=, or a purpose-built view for a specific consumer. Do not create /orders-mobile — that path leads to two APIs to maintain and two places for bugs to hide.

HTTP Methods and Status Codes: Semantics You Can Defend

Safe versus idempotent

Safe means the request does not change server state. Idempotent means repeating it has the same effect as doing it once. GET, HEAD, PUT and DELETE are idempotent by intent; GET and HEAD are also safe. POST is neither by default. Interviewers keep asking because the distinction is exactly what makes retries safe or dangerous.

Choosing a status code

• 200 — success with a body, the common case for GET and for PUT/PATCH that return the updated resource.
• 201 — a resource was created; include a Location header.
• 202 — accepted for asynchronous processing; be clear that the work is not finished.
• 204 — success with nothing meaningful to return, typical for DELETE.

A 4xx is usually more honest than a 200 with an error body. If the request failed, say so in the status line; clients, proxies, dashboards and retry logic all read that line before they read your JSON.

The pairs people confuse

• 400 vs 422: 400 means the request was malformed or unparseable; 422 means it parsed fine but failed validation. Some teams use 400 for both — say which convention you would follow and why consistency matters more than the choice.
• 401 vs 403: 401 means you are not authenticated; 403 means you are authenticated but not allowed. Returning 401 for an authorisation failure tells the client to log in again, which will not help.
• 404 vs 410: 404 means not found, or found but hidden from you. 410 means it existed and is deliberately gone. Use 410 sparingly; it leaks that a resource once existed.

"Is POST always non-idempotent?" No. POST is non-idempotent by definition of the method, but a specific endpoint can be made idempotent in practice — a create endpoint that rejects a duplicate request with the same idempotency key, for example. Say that carefully; overclaiming here is a common way to lose points.

Idempotency, Retries and the Questions That Follow

Retries are the hidden theme behind a lot of REST API follow-up questions. Any client on a flaky network will retry, and any answer that ignores that is incomplete.

Idempotency keys

An idempotency key is a client-generated identifier sent with a request so the server can recognise a repeat and return the original result instead of performing the action twice. It solves duplicate side effects on unsafe operations, most often POST. It does not solve everything: it does not make a badly designed endpoint safe, it does not help if the client generates a new key on each retry, and it does not remove the need to think about what happens when the first attempt is still in flight.

Safe retry behaviour by method

• GET — safe to retry, since it should not change state.
• PUT — safe to retry if the client sends the full representation; the end state is the same.
• DELETE — safe to retry if deleting an absent resource returns the same outcome as deleting a present one.
• POST — retry only with an idempotency key or a natural uniqueness constraint.

At-least-once delivery, in plain language

Most systems guarantee that a message or request is delivered at least once, not exactly once. That means duplicates are normal, not exceptional. Your job as a designer is to make duplicates harmless: unique constraints, idempotency keys, or operations that converge on the same state no matter how many times they run.

Pagination, Filtering and Large Collections

Offset versus cursor

Offset pagination (?page=3&size=50) is simple, supports jumping to an arbitrary page, and is easy to explain to a client. Its weakness is stability: if rows are inserted or deleted while a user pages through, items shift and some are skipped or repeated. It also gets slower as the offset grows.

Cursor pagination (?after=<cursor>) is stable under writes and stays fast at depth, because the database can seek rather than count. The cost is that you cannot jump to page 47, and the cursor must be opaque and stable. Choose offset for small, slow-changing admin lists; choose cursor for feeds, logs and anything that grows.

Filtering, sorting and field selection

These belong in query parameters on the collection, not in custom endpoints. GET /orders?status=open&sort=-createdAt&fields=id,total is one endpoint that answers many questions. A custom /orders/open/recent endpoint multiplies your surface area and your test matrix. Keep the parameter names consistent across resources — if sort works one way on /orders, it should work the same way on /invoices.

Total counts on a huge table

An exact COUNT(*) over a large table can be expensive, and it is often a product decision rather than a technical one. Options worth naming: return a total only when the filtered set is small, return an approximate count, or drop the total and let the UI say "load more". Say which you would choose and what you would tell the product owner.

Versioning, Evolution and Breaking Changes

Three approaches, three trade-offs

• URI versioning (/v2/orders) — visible, easy to route and to cache, but it duplicates the surface and tempts teams to fork the whole API.
• Header versioning (Accept-Version: 2) — keeps URLs clean, but is invisible in logs and browser address bars, which makes debugging and support harder.
• Media-type versioning (Accept: application/vnd.example.v2+json) — the most "correct" by REST theory, and the hardest to explain to a partner's integration team.

There is no free option. Name the cost of the one you pick.

Additive versus breaking

Adding an optional field, a new endpoint or a new enum value is usually additive. Removing a field, changing a type, tightening validation or changing the meaning of an existing value is breaking. "We will never break the contract" is a weaker answer than describing how you would detect a break and manage it: contract tests, consumer-driven tests, usage telemetry per client, and a deprecation window with a clear sunset date.

Consumers behave differently

A mobile app you control can be updated, though not instantly — old versions linger in app stores. A partner integration may take months and a contract amendment. Internal services are usually the fastest to move but the easiest to forget. Tie your versioning choice to who actually calls the API.

Errors, Validation and Consistent Contracts

An error body a client can act on

Include a stable machine-readable code, a human-readable message, and optional field-level detail. For example:

{
  "code": "validation_failed",
  "message": "The order could not be created.",
  "errors": [
    { "field": "currency", "code": "unsupported", "message": "Currency must be a three-letter ISO code." }
  ]
}

The code is what client code branches on. The message is for humans reading logs. Keep codes stable across releases — renaming one is a breaking change, even if the HTTP status stays the same.

Validation at the edge versus in the domain

The edge checks shape: required fields present, types correct, lengths within bounds, formats parseable. The domain checks meaning: this currency is supported, this transition is allowed, this user may do this. Both are needed; they answer different questions. If you describe only one, an interviewer will ask about the other.

Consistency as a maturity signal

If one endpoint returns {"error": "..."} and another returns {"errors": [...]}, clients accumulate special cases. Consistency across endpoints is one of the clearest signals of a team that has thought about its API as a product. When asked what a good contract looks like, describe one endpoint fully — method, path, request, success response, error response, and the guarantees you make about each — rather than listing principles.

Authentication, Authorisation and Rate Limiting at a High Level

Keep this conceptual. Interviewers usually want the model, not a walkthrough of a specific library.

• Tokens versus sessions: tokens suit stateless, multi-service and mobile clients; sessions give you easy server-side revocation and a simpler mental model. Name the trade-off — revocation and statelessness pull in opposite directions.
• Scopes versus roles: roles describe who someone is; scopes describe what a token may do. Scopes travel with the token and survive across services, which is why they scale better for third-party access. Roles are often simpler for internal users.
• Rate limiting: it belongs at the edge, in front of your application, so it protects everything behind it. Return 429 Too Many Requests and include a Retry-After header so well-behaved clients can back off instead of hammering you.

If you do not know the team's convention, say so usefully: "I would check the existing standard first — consistency with what is already deployed usually beats my preference — and if there is no standard, here is what I would propose." That is a real answer, not an evasion.

Practising REST API Answers Out Loud

Reading this article is not practice. Speaking is.

1. Rehearse the four-part pattern — constraint, default, trade-off, change condition — until it sounds like your own speech rather than a template.
2. Record yourself answering three questions: "What is REST?", "PUT or PATCH?", "How would you paginate a large collection?" Listen for places where you listed options without choosing one. That is the habit to fix.
3. Prepare two or three real examples from your own work, described honestly and without inflated scope. A small, well-explained decision beats a grand one you cannot defend.
4. Expect the follow-up. After "I would use cursor pagination", the next question is likely "what breaks?" Have the answer ready.

You do not need a specific framework to answer these questions. Framework details change; the reasoning about resources, methods, idempotency and contracts transfers. If you want to work through a related set of questions at the language level, the Python Interview Questions: Concepts and Trade-Offs article uses the same reasoning-first approach. More practice material is on the Blog, and the Documentation covers how the product is intended to be used.

The takeaway: in a REST API technical interview, the winning move is not the most complete answer — it is the clearest decision, with its cost attached. Practise saying "I would do X, it costs me Y, and I would switch if Z" until it is automatic.

Frequently asked questions

What are the most common REST API interview questions?

Expect questions about resource naming and URL structure, the difference between PUT and PATCH, safe versus idempotent methods, which status code fits a given situation, how you would paginate a large collection, how you version an API, and what a good error response looks like. Most of these are really asking how you make a decision when two reasonable options conflict, so prepare a short reasoning pattern rather than a definition for each one.

How do I answer 'What is REST?' without giving a textbook definition?

Describe it as a set of constraints you apply to get useful properties. Name two or three constraints — statelessness, a uniform interface, cacheability — and then say what each one buys you and what it costs. For example, statelessness makes horizontal scaling easier but pushes session state onto the client. That turns a definition question into a design conversation, which is what the interviewer is looking for.

What is the difference between PUT and PATCH, and which should I say I prefer?

PUT replaces the whole representation at a known URL and is idempotent, so retries are safe. PATCH applies a partial change, which is more convenient for clients editing one field but is not naturally idempotent, so a retried request can apply the same edit twice. Say you default to PATCH for partial edits on large resources and switch to PUT when the client genuinely owns the full representation, then explain the retry consequence of each.

How should I answer follow-up questions about idempotency and retries?

Treat retries as the real subject. Explain that most systems deliver at least once, so duplicates are normal, and that your job is to make them harmless. Mention idempotency keys for unsafe operations such as POST, note that GET, PUT and DELETE are safe to retry by intent, and be honest about what idempotency keys do not solve — they do not make a badly designed endpoint safe, and they only work if the client reuses the same key.

Do I need to know a specific framework to answer REST API interview questions?

No. Framework-specific details change between versions and employers, and interviewers know this. What transfers is the reasoning: how you model resources, which method and status code you choose and why, how you handle duplicates, pagination and versioning, and how you keep error responses consistent. If you do know a framework, use it only as a brief illustration after you have given the framework-independent answer.

How can I practise REST API answers without memorising scripts?

Use a four-part pattern instead of a script: name the constraint, state your default, name the trade-off, and say what would change your mind. Record yourself answering three or four common questions and listen for moments where you listed options without picking one. Then prepare two or three genuine examples from your own work, described at their real scope, and rehearse saying them in about twenty seconds each.

Practise these answers out loud with the Documentation.