Status code for returning not found sub-resource
So let's say I have two resources: "Wallet" and "User". User and wallet have a one-to-one relationship. In my REST API, I give the opportunity to provide the User with another wallet by ID. Thus, a typical HTTP PUT request to move a user to another wallet might look like this:
PUT /api/user/3 HTTP/1.1
Host: api.myuserandwalletwebsite.com
{
"wallet_id": 15
}
This will update the user to use a wallet with id = 15. But what if the PUT request contains a wallet_id that is not found in the database; what should a REST API return? Just a 404?
Returning a 404 to a sub-resource that was not found seems odd to me, because a 404 would be misleading: you might think that the 404 is actually referring to the fact that the user was not found.
source to share
404 (Not Found)
definitely not the correct answer code. The response code you want is 422 (Unprocessable Entity)
.
The status code 422 (unprocessed entity) means the server
understands the content type of the request object (hence 415 (Unsupported media type) is not valid) and also the syntax of the request object is correct (thus the 400 (invalid request)
status code is not valid ), but could not process the contained instructions.
- RFC 4918
This is a well-understood and well-defined response code and can be found in the IANA-maintained HTTP (HTTP) Status Code Registry.
As a side note, you are not using HTTP PUT as per the spec. PUT must update the entire content of the resource in an idempotent manner. You must use PATCH or POST.
Alternatively, you might consider a pooling resource such as an endpoint / custom wallet. This may or may not make sense depending on the specifics of your API.
source to share
In my application using REST API, I try to follow the best practices described here: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api And I know many programmers who are good software developers provisions that also take care of this. So, as described in the best practices in the case of not found resources, simple use:
404 Not Found - When a non-existent resource is requested
This is the first case - general best practices.
Second: It's about REST-API best practices - this is your application logic: I think you have several options based on your application logic:
404 Not Found - When a non-existent resource is requested because You requested non-existing wallet
405 Method Not Allowed - You cant put because wallet not found and it is required for update
422 Unprocessable Entity - Used for validation errors because we have validation in our app that check for incomming requests
So, the specific status is only your decision. Remember that the option you choose will propagate to the rest of your logic app, so be consistent and consider a REST API such as a GUI that targets another application.
source to share
As you already mentioned: I would not use 404 either, because that would mean that the user cannot be found. Since you want to update your user resource and this update failed due to invalid data (invalid wallet link), I would prefer to use 400 Bad Request and add a meaningful message in an extra header field (e.g. X-Message: Wallet with ID 15 not found).
HTTP 422 Unprocessable Entity is also a good idea, but not covered in RFC2616. If this "extension" is not a problem, you can go with that.
HTTP 405 is incorrect here, as it means that the PUT method is not allowed at all on the users resource and that PUT will not be enabled when OPTIONS is included on a resource that is not.
source to share