REST 404 vs 400. Which one to use?

Question

If I have a REST resource as shown below:

GET http://www.example.com/customers/{customerId}/orders

And in case the provided customerId does not exist, should my server return a 404 (Not Found) or a 400 (Bad Request)?

Alethaalethea

Answer 1

I believe it should be a 404 status, since the request was valid, however no customerID was found.

Mahler

Answer 2

I would say that you should return 404 Not Found in this case.

To elaborate on the subject, my interpretation of the specifications in this instance are as follows:

400 Bad Request is to be used in cases where the request was successfully received by the application, and the application determined that something was wrong about the request: Either the endpoint doesn't exist, or the format or nature of request parameters/variables was incorrect/malformed in some way, rendering the request invalid.

This would stand in the example by @Trevor Conn, where the customerID in the request is of an invalid format (too long, too short, invalid characters, etc) and the lookup or action can simply not be attempted due to the error.

The 200 series of responses (as also mentioned by @Trevor Conn) indicates a successful processing of the request against a valid entity or subject.

204 No Content should be used in cases where a subject was found, or action was executed, and the true and valid output or result of the request is "Nothing."

As I understand it, this does a few things:

1. It removes ambiguity about the true content of the response. Where 200 indicates success, but the empty response may otherwise indicate some form of transport or response failure. You are telling the client explicitly: "We successfully found and/or did a thing, and the true response is nothing."
2. Further, while I do not use this code myself, I believe the current browser support prevents replacing the content of the client. IE: if you were to click on a URL that hit an endpoint that returned 204 No Content, it would indicate to the browser that the request was successful, but would not actually navigate anywhere (both the viewport, as well as the current URI, would remain unchanged).

In your case, 404 Not Found would be the correct response to a request to a valid endpoint, with a correctly formatted customerID, that does not resolve to a Customer.

Going down the rabbit hole a little...

You could also track which valid customerIDs have been deleted/archived, and respond with 410 Gone if they did once exist, or 451 Unavailable For Legal Reasons if the Customer was removed due to a legal request.

Also of note, if you are working in a OOP language, you may be in an ecosystem where you consider endpoints/actions as "Methods."

If you are really going down the rabbit hole of HTTP Response codes, it is worth noting that the usage of 400 Bad Request handles missing "Methods" in this case. This is different from 405 Method Not Allowed, in that the the "Method" in Method Not Allowed refers to the HTTP Method (GET/POST/PUT/DELETE). 405 should be used, and only used, in cases where the client attempts to use one of these methods against an endpoint that does not support that method.

An example of this would be using:

DELETE http://www.example.com/customers/{customerId}/orders

Where the correct usage would be:

DELETE http://www.example.com/customers/{customerId}/orders/{orderID}

And further down the rabbit hole: the "Not Allowed" strictly refers to whether or not the method is implemented, and if the user lacks the permissions to execute an otherwise implemented HTTP Method, the correct response would be 403 Forbidden, or 401 Unauthorized if the client's permissions can not be determined because the client has not authenticated at all yet.

More Rabbit Hole...

501 Not Implemented is a server indicator of HTTP Method failure (in that the server it's self, be it Nginx, Apache, or any other) does not, at a foundational level, support the HTTP Request Method.

IE:

EXPELLIARMUS http://www.example.com/customers/{customerId}

205 Reset Content is similar to 204 in that it indicates success of the request, as well as a truly empty response, except that it indicates to the client to reset it's document view in-place (where 204 does not trigger any action at all).

Usurer

Answer 3

There are a few different ways to go with this.

If you're type checking the {customerId} and find that it's completely bogus, then a 400 - Bad Request makes sense.

However if the {customerId} is of a valid format and type but it just doesn't exist, then I would propose a 204 - No Content. In my opinion such a case is not properly a 404 since the action was found.

Assuming the user provides a valid path, even if customerId 123456 doesn't exist, then the call executed successfully and returned no data. Therefore 204 No Content.

Statuses in the 200 range are also considered "success" statuses so you can verify that your call did succeed for a correctly formatted {customerId}. Determining whether that Id is valid is probably the responsibility of another service however.

Christophe

No content should only be returned if a content source is found and there is no content in it (zero bytes beyond standard headers). If a content source is not found (no user with that ID), 404 is the correct response. – Usurer

Mike: That sounds like an answer more than a comment - can you provide it as an answer (so you get credit)? – Seigneury

@mike Sorry, forgot to tag you. I think I agree, but the philosophical difference is interesting. – Seigneury

Answer 4

If we consider /customers/ as the resource and the customerID is just a query param used to filter the resource, in that case, returning a 404 is incorrect.

With that considered, we can return a 204 No Content HTTP Status Code which means that the resource /customers/ exists and the request is valid, has been correctly fulfilled, and there is no more information to send (which is the case because the returned list is empty), hence the answer 204 No Content is understandable and valid.

The “204 No Content” status code definition says:

The 204 (No Content) status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.

Here's a quick read that can solve your confusion about other confusing HTTP Status Codes - You're Not Using HTTP Status Codes Right

Grouse

A link to a solution is welcome, but please ensure your answer is useful without it: add context around the link so your fellow users will have some idea what it is and why it is there, then quote the most relevant part of the page you are linking to in case the target page is unavailable. Answers that are little more than a link may be deleted. – Maletta