REST API Design Interview Questions: Idempotency, Pagination, Status Codes and Versioning

By Preeti Verma

Almost every backend developer builds REST APIs, which is exactly why interviewers use them to test depth. Anyone can write a controller. Fewer people can explain why one endpoint design is safer than another.

These are the REST design questions that come up most, with the points a strong answer includes.

1. What makes an API RESTful?

REST is a style built on a few ideas: resources identified by URLs, standard HTTP methods to act on them, stateless requests (the server stores no client session between calls), and a uniform interface. In practice, most "REST" APIs mean JSON over HTTP with sensible resource URLs. A good answer admits that few APIs follow every REST constraint (such as hypermedia links), and that being consistent matters more than being pure.

2. How do you name endpoints?

Use nouns for resources, not verbs, and plural names:

  • GET /orders lists orders, GET /orders/42 returns one.
  • POST /orders creates one.
  • PUT /orders/42 replaces it, PATCH /orders/42 updates part of it.
  • DELETE /orders/42 removes it.

Use nested paths only when the relationship is real and shallow: /orders/42/items. For actions that do not fit a resource, a clear sub-path such as POST /orders/42/cancel is acceptable, and saying so shows pragmatism.

3. What is the difference between PUT and PATCH, and between PUT and POST?

  • PUT replaces the whole resource with what you send (and is idempotent).
  • PATCH changes only the fields you send.
  • POST usually creates a resource where the server picks the id, or triggers an action, and is not idempotent by default.

4. What is idempotency, and why does it matter?

An operation is idempotent if doing it once or many times leaves the system in the same state. GET, PUT and DELETE are idempotent by design. POST is not: send it twice and you may create two orders.

This matters because networks fail. If a client times out and retries, you do not want a second payment. The standard answer for POST is an idempotency key: the client sends a unique key in a header, the server stores the result for that key, and a repeat request with the same key returns the stored result instead of repeating the work. Payment APIs work this way.

5. Which status codes should you know?

  • 200 OK, 201 Created (return the new resource and a Location header), 204 No Content (success, nothing to return).
  • 400 Bad Request (malformed input), 401 Unauthorized (not authenticated), 403 Forbidden (authenticated but not allowed), 404 Not Found, 409 Conflict (for example a duplicate or a version clash), 422 Unprocessable Entity (valid format, invalid data), 429 Too Many Requests.
  • 500 Internal Server Error, 502/503/504 for gateway, unavailable and timeout problems.

The follow-up to expect: "401 vs 403?" 401 means "I do not know who you are", 403 means "I know who you are, and the answer is no".

6. How do you handle errors consistently?

Return a consistent error body with a machine-readable code, a human message, and details for field errors. There is a standard shape called Problem Details (RFC 7807). In Spring Boot, handle exceptions in one place with @ControllerAdvice and @ExceptionHandler, so controllers stay clean. Never leak stack traces or internal messages to clients.

7. How do you design pagination?

Never return an unbounded list. Two common approaches:

  • Offset pagination (?page=3&size=20): simple, supports jumping to a page, but slows down on deep pages and can show duplicates or skip items if data changes between requests.
  • Cursor (keyset) pagination (?after=<id>&limit=20): efficient on large tables and stable when data changes, but you cannot jump to an arbitrary page.

Say you would return the total or a "next" link where it helps, and cap the maximum page size.

8. Filtering, sorting and searching

Use query parameters: GET /orders?status=PAID&sort=createdAt,desc. Whitelist the fields that can be sorted or filtered on, so clients cannot trigger slow queries or expose internals. Index the columns you filter on.

9. How do you version an API?

Common approaches: in the path (/v1/orders), in a header, or through content negotiation. Path versioning is the simplest and most visible. A better answer adds the real skill: avoid breaking changes in the first place by only adding fields, never removing or changing meaning, and giving clients time and notice before you retire a version.

10. How do you make an API cache friendly?

Use HTTP caching correctly: Cache-Control headers, and ETag with If-None-Match so a client gets a 304 Not Modified when nothing changed. Only cache safe, shared data, and be careful with anything user-specific. This ties to the wider caching questions in our guide on Redis and caching interview questions.

11. How do you protect an API from overuse?

Rate limit by user, key or IP, and return 429 with a Retry-After header. Validate request size, add timeouts, and authenticate every endpoint that needs it. If asked how to build the limiter, see how to design a rate limiter.

12. How do you validate input and avoid trusting the client?

Validate on the server, always. In Spring, use Bean Validation annotations (@Valid, @NotBlank, @Size) on request objects and return clear 400 or 422 responses. Never expose your database entities directly. Use separate request and response objects (DTOs), which also lets you change the database without breaking clients.

13. Synchronous vs asynchronous operations

For work that takes long, return 202 Accepted with a link to check the status (GET /jobs/123), or notify the client later with a callback or event. This avoids long-held connections and timeouts.

14. How do you document and test an API?

Document with an OpenAPI specification (Swagger UI is the common tool), which also lets clients generate code. Test at several levels: unit tests for logic, integration tests against a real or containerised database, and contract tests so clients and servers agree on the shape.

A mini design question to practise

"Design the API for a to-do app." A strong outline: resources (/lists, /lists/{id}/tasks), the methods, status codes, pagination for tasks, an error format, authentication, idempotent updates, and versioning. Then say what you would not build yet. Talking through choices and limits is what the interviewer is scoring.

Related reading: Spring Boot interview questions with scenarios and how to design a URL shortener, which uses many of these ideas.

Practise this on GenQuest

  • Start a voice mock interview: answer out loud to an AI interviewer that knows your resume and the role, get follow-up questions, then read a scored report with a question-by-question review. Your first 15-minute interview is free.
  • Open the question banks: Core Java scenarios, Blind 75 and NeetCode 150, high-level and low-level design questions, and company-wise sheets, with a free preview and progress tracking.
  • Ask the AI Coach: paste any question you are stuck on and get it explained in plain words, with a short answer you could say in an interview. See how it works in our AI Coach introduction.

FAQ

Is GraphQL or gRPC asked instead of REST? Sometimes as a comparison. Know that GraphQL lets clients choose their fields (and can reduce over-fetching), and gRPC uses a compact binary format that suits service-to-service calls. Say REST remains the common default for public APIs.

Should I use PUT or PATCH for updates? Use PATCH for partial updates, PUT when the client sends the full resource. Whichever you pick, document it.

What is HATEOAS? Including links in responses so clients can discover what they can do next. Know the idea, and be honest that many production APIs do not use it.

The takeaway

Know the methods, idempotency, status codes, pagination and versioning, and explain each with a reason and a trade-off. A designer who can say "here is the risk and here is how I handle it" will do well in this round.