I'm attempting to bulk geocode a set of addresses through the REST API from a Node.js client using the /geocodeAddresses?f=json endpoint. The problem is that if I send 50 addresses, and one of them is unmappable, the entire request comes back as a 500 server error:
{"errors":[{"errorCode":"INTERNAL_ERROR","errorDescription":"An error occurred while processing request, null"}]}
Is there a way that I'm not understanding to tell it to return the rest of the results without scramming the entire request? Sending them one at a time is unrealistic due to the volume of addresses involved.
Example (this will return only a 500 response, instead of one mapped and one unmapped result):
addresses={"records":[{"attributes":{"OBJECTID":1,"SingleLine":"9999 PENNSLYVANIA AVE NW,WASHINGTON,DC,20500"}},{"attributes":{"OBJECTID":1,"SingleLine":"1600 PENNSLYVANIA AVE NW,WASHINGTON,DC,20500"}}]}
Appreciate any thoughts on this!
Related
Consider a server side procedure to implement an algorithm and an API endpoint used to execute the algorithm on the provided input data.
To fix the idea imagine that the request content describes a travel between two places and that the server side algorithm is used to compute the time needed to complete the travel. Imagine also that many algorithms exist to compute the travel time and that the algorithm selection is somewhat based on the request content (the client calling the API endpoint can specify that he doesn't want to use toll roads or maybe that he wants to use the least busy road possible).
This scenario is usually coded by using one of the variant of the strategy pattern.
Now image that the API client specifies that he wants to use the most scenic route and that our server side implementation does not include an algorithm to be used for this request (maybe the only available algorithms are "avoid toll roads", "least busy road" and "shortest path"). In this case the server is not able to handle the user request and some sort of error status code must be returned to the client.
Should I consider the server unable to handle the request hence returning a 5XX status code or the client request contaning invalid parameters hence returning a 4XX status code ?
Put another way, is the server unable to handle the request because of server-side issues or is the client sending an invalid / malformed request to the server ?
Mentionning
our server side implementation does not include an algorithm to be used for this request
It is client's responsability to use the API with existing "algorithms".
From what I understood of your problem, client doesn't explicitly send a parameter like ?algorithm=ASTAR.
Only two possibilities remain :
Server does understand the request but is not able to treat it. ?tollRoads=false is a valid parameter
Is there a fallback ? Can you redirect to any other algorithm ?
Yes => 300 you can redirect user to other URLs
No => 204/501 it's a valid request, but the server can't handle it
It's not a valid parameter => 400 user should not send such parameter
We are using a specific endpoint on our API to test if an e-mail address is already registered in our database. When it's not, what would be the right status code to return to the client ?
We cannot take a decision between 404, 204 and 200. There are a couple of articles over the net but all state pros and cons but it's not very clear.
200 says that the request was successful
204 says that the request was successful AND that the message body included in the response is 0 bytes long.
404 says that there is no current implementation associated with the requested resource
Which of these is correct really depends on your resource design.
Consider a database query with a where clause -- if there are no matching rows, then you get SUCCESS, with an empty result set. So the analogous thing in a HTTP response would be a 2xx status code, and a body that describes an empty set.
If you were using a JSON List as your representation of the set, then the representation would be two bytes long [], and a 200 status code would be appropriate. If you were using a json lines representation, with each record on its own line, then with no records you would have no lines, therefore a 0 byte representation and 204 would be a good choice.
What about a case where we have a simple web page, that tells you if the email address is registered or not? If it's registered, the server responds with a 200 message and a html document that tells you about the registration. If it isn't registered, then you get an html message telling you that the email address isn't registered... and a 200, because we were able to find the current representation of the resource.
And 404? 404 indicates to the client that there appears to have been a spelling error in the target-uri of the http request -- that there isn't even nothing to find.
It may help to understand that status codes are metadata about the HTTP response, which is to say that they are part of the application domain of transferring documents over a network, not about the business domain. They are there so that generic components, like caches, can do interesting things without needing to know any specifics about the domain in question.
Our web API is a facade to make our domain model look like a boring document store.
I think this problem is not trivial, so I would like to express it in detail
Domain:
I have an endpoint (api rest) that receives a date and time of an appointment that I want to block (which will later be reserved). The operation is simple, when receiving the date and time, it is blocked so that another client can not book an appointment on the same day and time, while the one that blocks the appointment, completes the contact information.
So far, very simple. The problem begins when two different users select the same date and time in their browser and two requests are triggered simultaneously. As we already know, you can not block an appointment on the same day and time twice, so the application will fail (although this failure is properly controlled).
In short, two users try to block an appointment on the same date and time, and only the request that is processed first will succeed.
For the user who managed to block the appointment, the answer is clear: 200 OK status. The question is, which state code http corresponds to return to the second user?
Comment:
Very recently at work I have run into this dilemma, and I have argued strongly with a co-worker about it. Since then, I began to research hard and consult with several people with years of experience in the subject to be able to reach a conclusion.
2xx: Half of the people answered that the state code should be a 2xx. Why? first of all, because the request is well formulated (mainly the parameters, are written correctly) so it would not correspond to a client error (4xx) and on the other hand, it is not an unexpected error of the server (500), since it is duly controlled by the business logic itself. Since the query was done properly, it should send a 2xx status (more precisely a 200) indicating that the request was successful, with a message on the body, indicating the "status" of the action (the appointment could not be blocked) .
4xx: My position (and also that of the other 50% of those consulted) is that, as can be seen, the request fails because the desired action can not be completed. It does not seem logical at all, that a 200 OK is returned (indicating that everything went well) and a message describing the error or condition that occurred (in a way, it would be contradicting me). As an error occurred, there are only 2 possible guilty: the client and the server. In this case, it seems to me that the server is not, because it does not fail unexpectedly, but that business rule is well contemplated, and intentionally fails (so it would not be a 5xx). Everything seems to fit in that it is a client error, perhaps a semantic error, when trying to perform the same operation twice on the same resource. Therefore, my opinion is that an error 400 would adjust to the situation, and perhaps if we want to be a little more specific, a 409, indicating that we tried to modify concurrently a resource that does not allow this action.
What should be the appropriate option for this case?
Thanks!
Let us look at what the Wikipedia and MDN has to offer on this:
2xx (Successful): The request was successfully received, understood, and accepted
4xx (Client Error): The request contains bad syntax or cannot be fulfilled
(source: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
In the case of an appointment conflict, the request of the second user is received and understood but can not be accepted so it would seem to be wrong to return a 2xx for such a case.
A situation qualifies for a 4xx either when the request contains a bad syntax (which is not the case here as the request is well-formed) or when the request cannot be fulfilled (which seems to be the case here which you want to communicate back to the client).
A suggestion can be to go ahead with 422 for such kind of errors which are specific to a business use case (such as an appointment scheduler for your case)
As per MDN:
The HyperText Transfer Protocol (HTTP) 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
(source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422)
Also since booking an appointment would create a resource in the back-end (i.e. a valid appointment id with the details of visitor, time, etc.), I would prefer to send back 201 (Created) status code for the success case as you are executing the task in a synchronous manner. In my opinion, 200 (OK) status code is more suitable for situations when the resource would be asynchronously created and may not immediately be available when the server responses back to the client. In such cases we generally provide a GET request link from where the client can fetch the requested resource in future.
There is a Patch request on my application that updates a user's password. We have an Ember validator to block all invalid input except for 1 business rule, which is it should not be a password used as one of your past 5 passwords.
We are currently returning a 400 Bad Request in this case, however my company has a dashboard for component availability and counts 400 and 500 requests as unavailability, because most applications are SOAP and they just expect 200 and 300s. Even though we handle this 400 appropriately through the UI it is still a ding against us. And puts us on the radar as an area with poor availability.
Should we take this to the people that monitor availability and have them change this for REST services as this will become a more common and common occurrence as the company creates more REST applications. Or do we cave and return a 200 that also states that the password was not successfully updated?
I would argue that a 400 response is inappropriate for the service. If the service is responding with a 400 when the user's password has been repeated within the last 5 passwords, then the request was understood by the server.
According to the W3C:
The request could not be understood by the server due to malformed
syntax. The client SHOULD NOT repeat the request without
modifications.
In your case, the request was understood. It is returning a 400 to signal an application concern (regarding password reuse). I believe a 200 response would be more appropriate with a payload indicating the application problem.
EDIT:
One might also argue that a 422 response would be in order:
The 422 (Unprocessable Entity) status code means the server
understands the content type of the request entity (hence a
415(Unsupported Media Type) status code is inappropriate), 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. For example, this error condition may occur if an XML
request body contains well-formed (i.e., syntactically correct), but
semantically erroneous, XML instructions.
What's the best HTTP status code to use in response to an HTTP GET for a resource that's corrupt or semantically invalid?
E.g., consider a request to GET /person/1234 where data for person ID 1234 exists on the server but violates some business rule, so the server refuses to use it.
404 doesn't apply (because the data actually exists).
4xx in general seems not ideal (because the problem is on the server end, not under the client's control).
503 seems to apply to the service as a whole, not a particular resource.
500 certainly fits, but it's very vague in actually telling the client what might be wrong.
Any suggestions?
After reading the comments and the linked resources, it looks like #RemyLebeau's approach is best:
I think 500 is the only official response code that fits this situation. And there is nothing stopping you from including a response body that describes the reason for the failure.
according to iana.org:
4xx: Client Error - The request contains bad syntax or cannot be fulfilled
5xx: Server Error - The server failed to fulfill an apparently valid request
I think none of the 4xx status code should be valid as a response to an internal server error or migration or ... where client has no responsibilities or where user's inputs are expected to be rechecked. unless user's pre-filled data are involved like maybe user's package is not allowing him to access that data after a pre-determinate and known date, in such specific case It may be valid a 403 Forbidden as #Bari did suggest.
I'm not an expert but I think when the rejection or the decision of considering endpoint data as corrupt or invalid is made by server, then it will depends on what should be done next. I see 3 possible cases:
1. It is expected that somehow this is going to be fixed and client
should be invited to request it back but at some future moment ==> 503 (Service Unavailable):
503 (Service Unavailable)
status code indicates that the server
is currently unable to handle the request due to a temporary overload
or scheduled maintenance, which will likely be alleviated after some
delay. The server MAY send a Retry-After header field
(Section 7.1.3) to suggest an appropriate amount of time for the
client to wait before retrying the request.
2. Something is wrong, it is not client responsibility but there is an alternative way to access data, maybe following a specific process or sending further details ==> 510 Not Extended
2. Server cannot fulfill the request but there is an alternative way that requires it to include further details. Example: when requested data is corrupt, server error response may include a list of older (or unsaved, unversioned) versions of it and expect client to be more specific about which version to select so it could be fetched instead of the corrupted one ==> 510 Not Extended
510 Not Extended
The policy for accessing the resource has not been met in the
request. The server should send back all the information necessary
for the client to issue an extended request. It is outside the scope
of this specification to specify how the extensions inform the
client.
If the 510 response contains information about extensions that were
not present in the initial request then the client MAY repeat the
request if it has reason to believe it can fulfill the extension
policy by modifying the request according to the information provided
in the 510 response. Otherwise the client MAY present any entity
included in the 510 response to the user, since that entity may
include relevant diagnostic information.
case 2 was updated to include an example as IMHO it may fit in such case. but again I'm not any expert and I may be
wrong about it
3. No alternative ways, nothing to be expected or none of the other cases ==> 500 should be good
500 (Internal Server Error)
status code indicates that the server
encountered an unexpected condition that prevented it from fulfilling
the request.