I encounter the following case:
I have an API that allows me to retrieve a unique resource:
GET myapi/resource_id
If this resource does not exist, I return a 404 HTTP status code.
This API also allows to retrieve several resources via the same request:
GET myapi/resource_id1,resource_id2
Which HTTP status code should I send back if one of the two resources does not exist?
200 with an explanation in the JSON in an error key
206 which allows to be more explicit with an explanation in the JSON in an error key
400 / 404 code but this is not fine because the API still returns one of the two information
another solution?
Thank you for your help.
I think there are 2 options here.
Send back 200 and don't even mention the missing resource.
Send back 404 with an empty body.
The 206 is for range requests, the 400 is for malformed requests, so none of those apply here.
Related
This question already has answers here:
What is the proper REST response code for a valid request but an empty data?
(28 answers)
Closed 1 year ago.
If someone could please help settle this argument we might actually get this system finished LOL :^)
So, if you have a REST API.. for.. say.. returning patient details...
And you send in a request with a patient id...
But no patient with that patient id actually exists in the database..
What response should your API return?
1. a 404 ?
2. a 204 ?
3. a 200 with something in the body to indicate no patient found..
Thanks
Use a 404:
404 Not Found
The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean
that the endpoint is valid but the resource itself does not exist.
Servers may also send this response instead of 403 to hide the
existence of a resource from an unauthorized client. This response
code is probably the most famous one due to its frequent occurrence on
the web.
From MDN Web docs https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
What response should your API return?
It Depends.
Status codes are metadata in the transfer of documents over a network domain. The status code communicates the semantics of the HTTP response to general purpose components. For instance, it's the status code that announces to a cache whether the message body of the response is a "representation of the resource" or instead a representation of an error situation.
Rows in your database are an implementation detail; as far as REST is concerned, there doesn't have to be a database.
What REST cares about is resources, and in this case whether or not the resource has a current representation. REST doesn't tell you what the resource model should be, or how it is implemented. What REST does tell you (via it's standardized messages constraint, which in this case means the HTTP standard) is how to describe what's happening in the resource model.
For example, if my resource is "things to do", and everything is done, then I would normally expect a GET request for "things to do" to return a 2xx status code with a representation announcing there is nothing to do (which could be a completely empty document, or it could be a web page with an empty list of items, or a JSON document.... you get the idea).
If instead the empty result set from the database indicates that there was a spelling error in the URI, then a 404 is appropriate.
It might help to consider a boring web server, and how retrieving an empty file differs from retrieving a file that doesn't exist.
But, as before, in some resource models it might make sense to return a "default" representation in the case where there is no file.
if you have a REST API.. for.. say.. returning patient details...
Is it reasonable in the resource model to have a document that says "we have no records for this patient"?
I'm not a specialist in the domain of medical documents, but it sounds pretty reasonable to me that we might get back a document with no information. "Here's a list of everything we've been told about this patient" and a blank list.
What response should your API return?
If you are returning a representation of an error - ie, a document that explains that the document someone asked for is missing, then you should use a 404 Not Found status code (along with other metadata indicating how long that response can be cached, etc).
If you are returning a document, you should use a 200 OK with a Content-Length header.
204 is specialized, and should not be used here. The key distinction between 204 and 200 with Content-Length 0 is the implications for navigation.
I have a Restfull API which manages products. I already have a POST request to create a product and I would like to add a POST endpoint (postByCode) with a barcode in the body.
This new endpoint will use another API to create the product by retrieving the informations from it.
First question, what kind of HTTP status shall I use in case of the external API doesn't know the barcode (currently I return a 404 which is weird for a POST) ?
Sometimes, the exernal API knows the barcode but doesn't have the needed informations so I need to return the partial product for the user to update missing informations.
Second question, is it clean to return the partial product in my postByCode with a 307 HTTP Status ?
I'm thinking about replacing my postByCode by a getByCode and use the standart POST endpoint but it implies to do 2 calls for each product so a clean way to do it with a single request would be great.
Thank you in advance :)
First question, what kind of HTTP status shall I use in case of the external API doesn't know the barcode (currently I return a 404 which is weird for a POST) ?
Keep in mind that you've got the message-body of the response to describe the problem in detail to the client (think of how we would handle this on the web - the response would be an HTML document that the browser could render, so that the human can read that there is a problem and here are some suggestions on how to fix it, and the link to the FAQ, and so on).
The response code itself is general purpose metadata - something primarily intended for general purpose use. By choosing to send an error (4xx or 5xx), you've done most of the important work.
Reasonable candidates here include
400 Bad Request
403 Forbidden
409 Conflict
422 Unprocessable Entity
409 and 422 share the advantage that they call everyone's attention to the request message-body as the source of the problem. I would guess to use 422 in your case, but it somebody wanted to argue for 409 instead I would certainly listen.
Second question, is it clean to return the partial product in my postByCode with a 307 HTTP Status ?
I don't like 3xx for that case at all. I'd strongly prefer 4xx ("I didn't do it, here are links to the things that we need to do first") or 2xx ("I did some of it, but there are additional steps to consider").
I am using Blogger API v3. When requesting a list of scheduled status posts, the API always returns error 500. First I thought it might just be my blog or my app. However, I've tested on the API's own website (try it out) on a newly created blog and it still happens. Does anyone else have this same problem? Thanks in advance.
EDIT: Of course, this is assuming you already have scheduled posts in your blog though.
The 500 Internal Server Error is a very general HTTP status code that
means something has gone wrong on the web site's server but the server
could not be more specific on what the exact problem is.
Reference : https://www.westhost.com/knowledgebase/display/WES/What+Is+A+500+error
Q : Does anyone else have this same problem?
A : Yes, I have, several times.
In fact, the 500 error is not only happen when we request a list of posts but also in every request we can make with Blogger API. AFAIK, when I do a request with Blogger API and it's returned 500 error, it's always because when doing multiple request in almost the same time (usually because of looping which I forgot to break)
I've also encounter this error when testing it straight from the Blogger API examples page. The first time I request it retured 500 error, but the second time, the request the returned the data that I requested.
For the sample in Blogger API site, it may be just an authentication error. As for the error by your own request, I suggest you to check your coding again, the the request may be placed inside a looping or you've send a request BEFORE the previous request has successfully returned a response.
I would like to get data about city bikes - Dublin bikes- a bike sharing scheme run by JC Decaux. The information is available in real time from their website via an API. I have never gotten information from an API and cannot seem to work it.
I am using hurl.it just to check the structure of what I am requesting. I am attempting to get a list of the stations as denoted here: (https://developer.jcdecaux.com/#/opendata/vls?page=dynamic)
With this HTTP request:
GET https://api.jcdecaux.com/vls/v1/stations HTTP/1.1
Accept: application/json
I have put
https://api.jcdecaux.com/vls/v1/stations&apiKey={apikey} HTTP/1.1
into the "Destination" field. and "Accept" and "application/json" into the two "Header" fields.
I have tried many variations of this and nothing is giving me anything other than a 404 Not Found response. I am using an actual key for the api key after signing up.
Am I using this hurl.it site correctly?
First you need to get an API Key. Go to
https://developer.jcdecaux.com
to get one.
You can use your key in the URL like so: https://api.jcdecaux.com/vls/v1/stations?contract=dublin&apiKey=yourapikey
I have a scenario where my API application contacts external datasources and for this particular example, my API requests a list of colours from the external datasource. Sometimes the datasource doesnt have these colours and returns a plain text response of "There are no options to display" with a HTTP status code of 200 OK.
What i am wondering is what status code i should return to the client which is consuming my API in this scenario? A 404 not found or 204 no content...? Im not sure what would fit best.
Thanks
Is it valid not to return any colours? In which case your original 200 may be the right status code to use.
204 is normally used to indicate success, but the client need not update any information it holds; deleting or updating a resource for example are valid times to use 204.
404 seems wrong if the same URL is being accessed, in your scenario it sounds like the state of resource may change overtime (and it may be empty), but it always exists.