Building a RESTful web service endpoint and wondering what the best practice is for HTTP header status versus the status found in the body of the response. Should they always match, or can they be different? For example, in the event of a bad request, it's really our application layer that does the parsing and processing of the payload. So in the event the request made it to the application layer, should the HTTP header show a 200 (indicating no problems with the transport) while the response body contains a 400 (indicating a bad request)? Or should they always match? Both 400 at the header and in the body?
Thanks.
Generally speaking, it is a good practice to be consistent. Thus, if you intend to return the HTTP status code in your JSON body, it should be the same as the HTTP status code.
If you want to add more details regarding your application errors. The JSON-API standard defines some fields for JSON error bodies, such as:
code: an application-specific error code, expressed as a string value. For example, you could have different codes for HTTP 400 status code.
title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail: a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
Imagine that your application has the following route to get the details of a song (identified by :id parameter) that belongs to an artist (identified by :artist_id parameter):
GET /artists/:artist_id/songs/:id
This request may produce two different Not Found errors:
when the artist is not found
when the song is not found
For both situations you will return a HTTP 404 status code. However, in your json body you can add more details:
when the artist is not found
code: 10
title: Artist Not Found
detail: The artist with id #{artist_id} does not exist
when the song is not found
code: 12
title: Song Not Found
detail: The song with id #{id} does not exist for #{artist.name}
I also recommend you take a look on how JSON-API standard defines HTTP error code
Related
In our API, one of the endpoint will expect clients to provide body/payload only in certain scenario.
If the API is unable to generate a payload for given request based on the origin of the client then, we want our API to provide response with the right status code to the client, so that they know they have to provide additional information. Once the client fulfills the request with body/payload then the api will process the request as normal.
I just wanted to know is there any standard, predefined status code or procedure to implement this kind of endpoint in API design or do we have to just reject the request with some custom status code and then ask the client to implement a logic based on custom code?.
Thanks,
Vinoth
HTTP Status codes don't, nor are they intended to, map precisely against every real world error. They represent categories of error.
For example, a 404 means that the resource couldn't be found, but if your path is /customers/11/animals/5 then there are several things which could be wrong with the path. customer 11 may not have an animal 5 for example, or there may be no customer 11. There is no http response for "animal not found". Or your API may not have any calls with that pattern of URL to begin with.
You should return a status code which represents what "category" of error you have (in this case, something was not found), and the response body should contain more specific details about the error. To make things simpler, I find it helpful if the data structure is the same for a success and error (it makes parsing much easier) with a "data" field which varies per response.
Here is one example:
status code: 404 not found
body: {
"messageDetailCode" :"CustomerNotFound",
"messageDetail" : "Customer not found",
"data" : null
}
Further reading:
What's an appropriate HTTP status code to return by a REST API service for a validation failure?
/persons?age=18
Imagine a search does not return any results (means: no entity found for the request).
If I'd return a 404 here, that would suggest that maybe the /persons path is invalid entirely.
Is there any accepted status code that could be return if the request was valid in general (means: the path exists, and the request parameters have been valid), but still there is no data to return?
204 is not suitable either, as this is used to tell the user "your request was 200 OK, but there will never be a response body to your request" (like for modifications).
Is there any accepted status code that could be return if the request was valid in general (means: the path exists, and the request parameters have been valid), but still there is no data to return?
200 is appropriate when the resource has a representation, even if that representation is an empty list.
# Request:
GET /persons?age=18
# Response:
200 OK
[]
Think "web search page that returns no results", downloading an empty file.
Jim Webber's 2011 talk may help with perspective here: the status codes and headers belong to the "transferring documents over a network" domain, not to your domain application protocol. The components that are specific to your application should be paying attention to the messages in the body of the response; the meta data is directed at general purpose components that are transferring documents.
Actually you should return 200.
The number of entities found does not change the http code.
I'm building a REST API and have a dilemma around the returning response code to a GET operation.
I've found many examples and answers online but not for my particular scenario.
Here is what I have found and understand so far:
if returning an empty list (say /library/authors/{authorId}/books) an empty list with a response code 200 will suffice
if requesting a specific resource with an id ( say /library/authors/{authorId}/books/{bookId} ) the response will be empty with a 404
That summarizes most of my use cases and I am fine with it.
However, what happens if I access a sub-resource without an id?
For example, for arguments sake, let's say the author can have many books, but only one auto-biography. He either has one or he doesn't. I don't expect the user to pass in the auto-biography id because the system can figure out on its own if one exists, the endpoint is something like this:
GET /library/authors/{authorId}/auto-biography
If the author exists but he has no autobiography (it is NULL), would the http response code be:
204 (empty content)
404 (resource does not exist)
Thank you in advance!
Working through the semantics
GET /library/authors/1/auto-biography
/library/authors/1/auto-biography is an identifier. The resource itself is some concept like "the auto biography of author 1"; notice that we can talk about the resource even though it may not actually exist yet.
A resource can map to the empty set, which allows references to be made to a concept before any realization of that concept exists
The thing that appears in the body of the HTTP response isn't the resource, but a representation of the resource.
So now look at the status codes
404
The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
204
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.
A loose analogy: suppose you try to get the contents of a file. 404 is semantically aligned with FileNotFound; 204 indicates the file is zero bytes long.
404 would normally be accompanied by "a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition." It indicates that the client tried to use a link that shouldn't have been available.
204, on the other hand, doesn't have anything -- the representation is zero bytes long, how could there be data. It's a special case of a 200 response, advising the client (and intermediary components) that the response body is intentionally left blank.
I have
/rest/drink/categories?alcohol=true
which is return 200 status code with list of drink categories that have alcohol in it, e.g.
200 ['wine','beer']
I wonder what status code should I use, if a user hit a none handled path like below
/rest/drink
or
/rest/drink?alcohol=true
404 - Not found if the URL does not exist,
400 - Bad request if the URL exists but the request parameter is invalid.
Http has status for such conditions.
4XX defines the error is from client side and needs a change.
Wiki says
The 4xx class of status code is intended for situations in which the client seems to have erred. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents should display any included entity to the user.[31]
For the condition where it is mentioned, its ideal to use 404 - Not Found or 400 - Bad Request
This gives list of all the status codes and appropriate explanation.
W3Org
defined the specifications for these.
So, I am trying to display meaningful and accurate HTTP status codes and I'm getting confused even after going through the examples online. Here's my situation:
In the URL which accepts the query param:
#POST query
Sample URL: /putRecord?Name=A&Age=25&house=permanent
what status code do i return when one of the params is missing? (All 3 are mandatory) - from what I've read, I am guessing it is a 400: Bad request. But this seems too general. Is there a way for me to say that the query was malformed? Source:here
Assuming I validate the name for duplicates against the DB, if I get a duplicate, what status code do I return?
So, if there's a duplicate entry available already, I can't add the record. Do I display 304 (Not modified) or just the error code from 2?
Clarification: For 3, another possibility is when I can't actually commit to the DB and I rollback(possibly). What status code will it be now?
Thanks so much!
Ad 1. You can return, besides the code itself (400) also a short message with explanation. So, instead of returing "400 Bad Request" you could respond with "400 Query param name required" or something similar. This message is called "reason phrase" and is defined in 6.1 in RFC 2616. Or, if you need more flexibility, you could return document with the explanation.
Ad 2. I would consider using 422 Unprocessable entity. From the RFC 4918:
The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity, and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions.
Ad 3. I would return 422, but it really depends whether this situation is considered an error in your logic, or is it a regular, expected situation.
Edit: As #War10ck suggested in the comment, HTTP 409 (in place of HTTP 422) might make sense as well.
Note on handling duplicates: it seems (correct me if I'm wrong) that you consider new entity being a duplicate if it's name is already in the database. If so, that you could maybe consider using a HTTP PUT instead of HTTP POST?
You could define the following resource:
HTTP PUT /record/:name
So, "name" would be a part of the URI. Then, in case there is a second PUT to the same resource (same "name"), it'd be elegant to respond with 409/422.
If you're using different key for unique constraint, modify the URI appropriately.
As a rule of thumb, POST is for situations where you can have multiple instances of a given resource, i.e.
HTTP POST /log ;; Because we have many logs
And PUT for situations where each resource is unique:
HTTP PUT /person/:name (or /person/:tax-number if :name isn't unique)
Also, note that I've renamed your resource from "putRecord" to "record" - PUT is a HTTP method, no reason to have it in URI as well.