1. Prompt and Use Case
Design a REST API that lets clients query collections, update profiles, and delete resources. The interviewer asks why some successful requests return 200 while others return 204, and how to represent an empty list, a missing resource, and a successful delete. Assume clients depend on a stable JSON contract and a gateway records response-body sizes.
2. What the Interviewer Is Testing
- Whether you understand that 204 means success with no message body, not simply an empty result.
- Whether you can discuss resource representations, collection semantics, and client parsing as one contract.
- Whether you know that RFC 9110 still permits useful metadata such as an ETag on a 204 response.
- Whether you can make predictable 200, 204, and 404 choices instead of memorizing one status code per method.
3. Clarifying Questions to Ask First
- Did the request change a resource, or did it read a representation of a collection?
- Does the client need a new JSON representation, pagination metadata, or a next link?
- Does “no result” mean a valid empty collection or a missing target resource?
- What are the idempotency semantics and product contract for repeated DELETE calls?
4. A 30-Second Answer Framework
First ask whether the successful response needs a representation: return 200 when the client needs JSON, pagination data, or resource state; return 204 when the operation succeeded and there is no message body to deliver. A valid empty collection remains 200 with [] because the collection representation exists; a missing individual resource can be 404. DELETE commonly uses 204, but an API that returns audit data or a response envelope should use 200. State that 204 must not contain a message body, then test both client paths.
5. Step-by-Step Deep Answer
Step 1: Separate an Empty Representation from No Representation
200 indicates a successful request and allows a representation. GET /users?team=none found a valid collection with zero members, so return 200, [], and pagination fields; the client can still decode the list contract. 204 indicates that the operation succeeded but the response has no message body, which fits an update or delete acknowledgement when no new representation is needed.
Step 2: Choose a Status for Writes
After a successful PATCH, return 200 and the resource representation when the client needs server-normalized fields, a version, or derived values. Return 204 when the client only needs confirmation, and use an ETag or another header to convey a version if useful. A successful DELETE commonly returns 204; return 200 when the API must return a revocation token, audit record, or response envelope. Keep the policy consistent across endpoints.
Step 3: Handle 404 and Repeated Requests
An empty list is not 404 because the collection resource exists. Requesting /users/42 when that resource does not exist is the 404 case. For repeated DELETE calls, define whether “already absent” is success: an idempotent DELETE can return 204 again without revealing existence, while a product that must tell the client the object never existed can return 404. Put the decision in the contract.
Step 4: Verify the Protocol and Client Behavior
A 204 response cannot contain a message body, so clients must not unconditionally parse JSON. Contract tests should cover status, Content-Length, headers, and an empty body; verify browsers, SDKs, proxies, and cache layers. If the resource version is sent as an ETag, the client can use it in a later If-Match request instead of putting an object representation into the 204 response.
6. High-Quality Sample Answer
I first ask whether the client needs a new resource representation. I return 200 when it needs an object, pagination fields, or a JSON envelope, and 204 when the operation is complete and there is no message body to deliver. A valid empty list is still 200 with [] because the collection exists; a missing individual resource is 404. PATCH can return 200 when the client needs the server-normalized result, or 204 with an ETag when it only needs confirmation. DELETE is usually 204, unless the API returns audit data. I verify that 204 has no body and that clients branch before JSON parsing, then document the repeated-DELETE policy.
7. Common Mistakes
- Returning 204 for an empty list → the client loses one list and pagination shape → return 200 with an empty collection representation.
- Putting a JSON envelope in a 204 response → violates the no-body constraint and creates proxy differences → remove the body or use 200.
- Assuming DELETE must always be 204 → ignores audit data or normalized output → choose 200 or 204 based on whether a representation is needed.
- Treating every empty result as 404 → confuses an existing collection with a missing member → identify whether the target is a collection or an individual resource.
- Parsing JSON for every 2xx response → 204 can cause a parse failure → branch on status and add contract tests.
8. Follow-up Questions and Responses
Follow-up 1: Can a GET with no matches return 204?
It can represent no body, but it breaks a list endpoint’s stable shape. When the query succeeded and the collection exists, prefer 200 with an empty array and pagination metadata; use 204 only when the API contract explicitly treats “no representation” as the result.
Follow-up 2: Can a 204 response include an ETag?
Yes. A 204 has no message body, but response headers can carry resource-version metadata. The client can save the ETag and send it in If-Match on a later conditional update without receiving the full object.
Follow-up 3: Should a repeated DELETE return 204 or 404?
Choose based on idempotency and information disclosure. If the post-delete state is simply “absent” and callers do not need to distinguish first and repeated calls, return 204 consistently. If callers must know that the resource never existed, return 404. Keep the choice stable in the API contract rather than varying by implementation path.