REST API Interview Questions

The Semantics of HTTP Verbs

A common interview question involves justifying the choice of specific HTTP methods. REST relies on the uniform interface constraint, meaning we must use verbs that semantically match the intended action on a resource. GET is idempotent and safe, meaning it should never change state. POST is neither safe nor idempotent; it is used to create sub-resources or trigger non-standard actions. PUT requires the client to supply the full representation of the resource, making it idempotent because repeating the request results in the same state. PATCH is used for partial updates, offering efficiency when only specific fields need modification. Understanding these distinctions is critical because they allow intermediary components, like proxies and caches, to handle requests safely without understanding the internal business logic of your application, ensuring the entire distributed system remains consistent and predictable during operation.

// Standard resource manipulation
// GET /users/123 -> Fetch data
// POST /users -> Create new entry
// PUT /users/123 -> Replace entire record
// PATCH /users/123 -> Update fields
// DELETE /users/123 -> Remove resource

Designing Resource URIs

Interviewers often test your ability to design URI structures that are intuitive and hierarchical. A well-designed URI represents a resource, not an action. Use nouns, not verbs, to define the endpoint structure. Pluralization is generally preferred to maintain consistency, such as /orders rather than /order. Hierarchy should reflect ownership or containment, for example, /users/{userId}/orders/{orderId}. This structure makes the API self-documenting and predictable for the client developer. Avoid exposing database table names or implementation details in the URI path. By keeping the URI clean and focused purely on the resource identification, you maintain a level of abstraction that allows the backend team to refactor their internal data storage logic or microservice architecture without breaking existing client integrations. This consistency is the cornerstone of building long-lived, stable API contracts that stand the test of time.

// Good: Resource-based hierarchy
// GET /customers/50/invoices/2
// Bad: Verb-based or RPC-style
// GET /getInvoiceDetails?id=2

Effective Error Handling

Proper error handling is vital for developer experience and debugging. Never use a 200 OK status code to report a failure; this misleads the client and breaks automated error-handling middleware. Instead, use appropriate 4xx codes for client errors, like 400 for malformed requests or 401/403 for authentication and authorization failures. Use 5xx codes for server-side issues. The response body should provide machine-readable error details, such as a unique error code, a human-readable message, and perhaps a reference link to documentation. By providing consistent error structures, you allow client developers to write generic error interceptors that can act globally. This reduces code duplication on the client side and provides a clear contract on how to troubleshoot issues, which is often a point of heavy scrutiny in senior-level architectural design interviews and system reviews.

// Error response format
// HTTP 400 Bad Request
{
  "error_code": "INVALID_EMAIL",
  "message": "The provided email is malformed."
}

Statelessness and Scalability

REST mandates that communication be stateless. This means that every request from a client must contain all the information necessary for the server to understand and process it, including authentication tokens and metadata. The server should never rely on session state stored in memory between two different requests. The reasoning behind this is horizontal scalability; if the server is stateless, you can easily add more nodes behind a load balancer without needing to synchronize session memory across them. If the client needed to talk to the same server node every time, your scaling ability would be artificially capped by the memory limits of a single instance. Embracing statelessness simplifies the architecture, improves performance during high traffic, and ensures your application remains robust even if specific server instances fail or cycle frequently during deployment.

// stateless authentication via tokens
// Header: Authorization: Bearer <token>
// The server validates the token on every request
// without needing a local session lookup.

Versioning Strategies

Versioning is inevitable in long-term API development. Interviewers want to see that you understand how to evolve your API without breaking existing client integrations. The most common approaches include URI versioning, like /v1/users, or header-based versioning. URI versioning is widely used because it is simple to cache and debug, though some argue it modifies the resource identifier. Header-based versioning keeps the URI clean but adds complexity to the client implementation. Regardless of the chosen strategy, the most important aspect is consistency. Always provide a deprecation timeline for older versions and communicate changes clearly. By planning for versioning early, you show that you acknowledge the reality of evolving business requirements and are prepared to maintain backward compatibility, ensuring that your API remains reliable for users even as you introduce new features or change underlying data models.

// URI Versioning approach
// GET /api/v1/users/1
// GET /api/v2/users/1
// Using versioning ensures that consumers 
// can upgrade their endpoints at their own pace.

Interview questions

All REST API Design interview questions →

Check yourself

Take the full REST API Design quiz →