REST API Design Interview Questions and Answers

An operation is idempotent when performing it multiple times produces the same server state as performing it once.

• GET, HEAD, PUT and DELETE are idempotent by HTTP semantics.
• POST is not idempotent; repeated calls may create multiple resources.
• PATCH is not guaranteed to be idempotent.

PUT /users/42/email

Idempotency matters for retries: a client or gateway can safely retry an idempotent request after a timeout. For non-idempotent operations such as payments, use an idempotency key so the server can detect and deduplicate retries. Note that idempotency refers to server side effects, not the response code: the same DELETE may return 204 the first time and 404 the second, yet the end state is unchanged.

401 Unauthorized means the request lacks valid authentication credentials. The client should authenticate and retry, and the response should include a WWW-Authenticate header describing the scheme.

403 Forbidden means the server understood the request and knows who the caller is, but the caller is not allowed to perform it. Re-authenticating will not help; the identity simply lacks permission.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

Practical mapping: a missing or expired token gives 401, while a valid token with an insufficient role gives 403. For sensitive resources, many APIs return 404 instead of 403 so attackers cannot learn whether a resource exists. Avoid returning 400 for permission failures, because it hides the real cause from clients and monitoring.

HATEOAS stands for Hypermedia as the Engine of Application State. A response not only carries data but also links describing the actions and related resources the client may follow next, so clients discover transitions at runtime instead of hardcoding URL templates.

{
  "id": 42,
  "status": "pending",
  "_links": {
    "self":   { "href": "/orders/42" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" },
    "pay":    { "href": "/orders/42/payment", "method": "POST" }
  }
}

Because the server decides which links exist, clients can adapt when workflow rules change. In practice full HATEOAS is rare: it adds payload size and clients often still hardcode behavior. It is the top level of the Richardson Maturity Model and is most valuable for workflow-heavy APIs with many valid state transitions.