I'm creating a REST API in PHP.
When the client may try to perform an action, which is unavailable, for example, it tries to change a property of the resource which is not passable: for example, tries to change the value of the "country" property to "Julius Caesar":
What HTTP status code should I send back with the response? I'm speculating between 403 and 409.
I don't know if 403 Forbidden is only related to user permissions or can I use for this purpose?
In what situation should I use 409 Conflict?
To summarize what is the proper HTTP response status to an illegal operation?
I think you should use a 403 Forbidden here.
From the HTTP specification:
The server understood the request, but is refusing to fulfill it.
Authorization will not help and the request SHOULD NOT be repeated. (...)
As you are refusing to change the value of "country", this is the status code you want to return. The client is not authorized to change the resource's country.
409 Conflict is not appropriate in this case. The 409 status is to be used when for instance somebody sends a request to update a resource, but their version of the resource is outdated because the resource has been modified in the meantime. In other words, there is a conflict between the client's data and the data on the server. This has nothing to do with allowing certain properties of the resource to be changed.
The request could not be completed due to a conflict with the current
state of the resource. This code is only allowed in situations where
it is expected that the user might be able to resolve the conflict and
resubmit the request. The response body SHOULD include enough
information for the user to recognize the source of the conflict.
Ideally, the response entity would include enough information for the
user or user agent to fix the problem; however, that might not be
possible and is not required.
Conflicts are most likely to occur in response to a PUT request. For
example, if versioning were being used and the entity being PUT
included changes to a resource which conflict with those made by an
earlier (third-party) request, the server might use the 409 response
to indicate that it can't complete the request. In this case, the
response entity would likely contain a list of the differences between
the two versions in a format defined by the response Content-Type.
(emphasis mine)
In this situation, I usually opt for a 400 Bad Request. I'm not sure if a more specific 400 range status code would fit better, however I would not use 403. For me, a 403 is security related, and should not be used for request payload validation errors.
As for 409 Conflict, I usually use this if the request is valid, but the state change is somehow illegal. However, I have seen it used in other contexts as well.
In the end, as long as you are consistent across your API (and document the meaning of the return status codes), you have some flexibility to decide how you want to express the error.
Related
If user has to upload files and confirm them via API endpoint call, what status code should be returned if user calls the confirm endpoint but has not uploaded all of the required files?
400 doesn't seem to be right because there is nothing wrong with the request parameters.
403 doesn't seem to be right because there is nothing wrong with credentials.
The 403 (Forbidden) status code indicates that the server understood the request but refuses to fulfill it.... a request might be forbidden for reasons unrelated to the credentials. -- HTTP Semantics
Keep in mind that status codes are metadata in the transfer of documents over a network domain; they tell HTTP components how to interpret the fields and body in the HTTP response.
See also Mark Nottingham on the generic semantics of status codes.
I don't think it is as good a choice, but it 409 conflict is an alternative that is probably harmless?
The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. -- HTTP Semantics
Our image board allows users to upload images by copy-pasting URLs. A client app sends a POST request to our API with an image URL given in the request body. Our web service receives the POST request and handles it by downloading the image from the given URL by using a server-side HTTP client (request in our case).
In successful case, the service finds the image, downloads it, and stores it to the server. The service returns HTTP 200 to the client.
Now, what if the image cannot be found? What if the download attempt results in HTTP 404? What HTTP error code should we use to response to the client?
HTTP 400 Bad Request is not applicable because the request was well-formed and all parameters were valid.
HTTP 404 Not Found is not applicable because the request URL was found and served although the image URL was not.
HTTP 502 Bad Gateway does not feel right either because there is nothing wrong with our server or the upstream server (the server of the source image). The user just happened to type in an image URL that does not exist.
Any experience on the matter? Which error code is the most correct?
First of all you should decide if this is a client error (4xx) or server error (5xx). From what you describe, it feels more like a client error. The client has requested the creation of a resource from another resource (the image URL) which does not exist.
There is no perfect match for this scenario, although one could make a case for each of the 2 following response codes:
HTTP 409 Conflict: From the RFC:
The request could not be completed due to a conflict with the current
state of the target resource. This code is used in situations where
the user might be able to resolve the conflict and resubmit the
request...
This applies to your case if you consider the target resource to be in a bad state (image not found). If someone provides an image at the specified URL, that effectively transitions your resource to a valid state.
This is also a good match because, as the RFC states, this code implies the user might be able to resolve the conflict (in your case the user would correct this by posting the image to the specified URL).
HTTP 424 Failed Dependency: From the RFC:
The 424 (Failed Dependency) status code means that the method could
not be performed on the resource because the requested action depended
on another action and that action failed...
This applies to your case in that "the requested action depended on another action and that action failed". The dependent action is the posting of an image to the other URL. What you have described is a case where that dependent action either failed or did not happen (which could also be called a failure).
Since the API determines on something that is not available, its service is unavailable as well.
The status code 503: Service Unavailable is the best fit for your situation.
According to the RFC description:
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.
Alternatively, if your API supports a way of communicating errors (e.g. to tell the user that the information he submitted is incorrect) you may be able to use this method to tell the user that the external resource is unavailable. This might be a little friendlier and might avoid some error raises on the user's side.
Since the client app sends POST requests to your API server the response codes should be generated according to the received server in your case this is your API server.
If the server has received correct information from the client app and server determines the request as valid, it should return apropriate code with proper JSON or header based error messages.
http error codes were conceived assuming that all pages possibly served were stored locally, one way or another.
Your scenario does not match that assumption and it should therefore not come as a surprise that you don't find codes that fit your bill properly.
Your "not found" scenario is in fact an application error and you should notify your user of the situation by providing an error message on the form where he entered the URL (or return a fully dedicated error page or some such). Or choose an http error nonetheless and accept the notion that it will be a poor fit no matter what.
Now, what if the image cannot be found? What if the download attempt results in HTTP 404? What HTTP error code should we use to response to the client?
The main thing to keep in mind: you are trying to fool the client into thinking that you are a web site - just a dumb document store which might respond to some content editing messages.
For the client, the primary means of communication is the body of the response. See RFC 7231
Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.
The status code is meta-data: aimed at giving the generic components participating in the exchange a chance to know what is going on (examples: the web browser doesn't need to know what page you are asking for to recognize a redirection response returned by the server, the web browser asking for credentials when it receives a 401 unauthorized response, web caches invalidating entries, or not, depending on the status code returned by the response).
HTTP 400 Bad Request is not applicable because the request was well-formed and all parameters were valid.
Yes, that's exactly right.
I would probably use 500 Internal Server Error, on the grounds that there's nothing wrong with the _document that the server received, the problems are all involved in the side effects of the server's implementation.
A different approach you might consider: 202 Accepted. Roughly translated "I got your message, I understood your message, and I'll get around to it later." If you don't need the side effects to be synchronous, you can defer judgment. That allows you to do things like applying a retry strategy.
The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled.
"I'll get to it later; if you want to know how it is going, go ask him -->"
Because 202 is a non-error status code, its effect on caches is different from those of a 4xx or 5xx. If you are already thinking ahead about caching, you'll want to the implications of that in mind.
Let's say we have an online shop and receive a valid request of updating some order.
The request is valid by itself, but let's say that the order has an expiration time, and it has already expired, so this request is unprocessable in fact.
I doubt if it is a kind of validation error or not. Because, as I stated above, the request itself is valid; and a request sender might not know that order has already expired.
What's an appropriate HTTP status code to return by a REST API service for such a situation?
Warning: Due to the general requirements for the product, it should be some of 4XX error codes!
UPD: More information: this putative "order" still exists, even being expired. It is possible to retrieve it, but it is not possible to operate it anymore. That's why the code 404 (for example) is not appropriate.
My own version:
I think that for such situation the 410 status code is most appropriate:
The 410 response is primarily intended to assist the task of web
maintenance by notifying the recipient that the resource is
intentionally unavailable and that the server owners desire that
remote links to that resource be removed. Such an event is common
for limited-time, promotional services and for resources belonging to
individuals no longer associated with the origin server's site. It
is not necessary to mark all permanently unavailable resources as
"gone" or to keep the mark for any length of time -- that is left to
the discretion of the server owner.
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html:
The requested resource is no longer available at the server and no
forwarding address is known. This condition is expected to be
considered permanent. Clients with link editing capabilities SHOULD
delete references to the Request-URI after user approval. If the
server does not know, or has no facility to determine, whether or not
the condition is permanent, the status code 404 (Not Found) SHOULD be
used instead. This response is cacheable unless indicated otherwise
I'll say that 400 fits better than 410.
IMO 410 (Gone) doesn't fit because the resource is not gone. It's still there, simply in kind of a final (in this case expired) state.
400 means BadRequest. Per my interpretation, trying to UPDATE something, that is not updatable (trying to update expired item) is a BadRequest.
I believe, that 400 is not only for badly formatted requests, but also for requests that does not meet internal business logic validation (in this case, not updating an expired item, is an internal business logic).
Use 410 Gone.
The target resource is no longer available at the origin server and that this condition is likely to be permanent.
I would choose one of these:
400 - Bad request
410 - Gone
from : https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
I am using HTTP HEAD request for checking is a userlogin name is available or not. Now I am returning a 200 OK response if the user login name is available, What do I return if login is not available? Should it be 409 or 403 or 410 (Gone).
I believe that 409 makes the most sense.
The request could not be completed due to a conflict (username already taken).
This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
Your response body SHOULD include enough information for the user to understand the username is already taken.
Edit
The 410 Gone response should only be used if requested resource is no longer available at the server and no forwarding address is known. These are for situations where the request-URI is not available temporarily. Some suggest to just use 404 if you think the URI will be down for long periods.
The 403 indicates a fundamental access problem. It is more difficult to resolve because the HTTP protocol allows the Web server to give this response without providing any reason at all. This is equivalent to a blanket 'NO' by the Web server - with no further discussion allowed.
My question is quite a generic one about HTTP status code when a DELETE is impossible on the resource (but not regarding user's rights).
We have a RESTful API on a type of resource.
The DELETE method is authorized on the resource however under some conditions a resource cannot be deleted (if there are data binded to this resource).
What is the correct HTTP status code to return to the client in this situation?
Here are some of the possibilities I gathered and why it seems inappropriate in my case :
403 (Forbidden) : Seems mostly related with user's rights.
405 (Method Not Allowed) : Seems like the API is not designed to respond to this method for this type of resource.
409 (Conflict) : Seems appropriate but the client should have the possibility to resolve the conflict with the API but that's not the case here.
Update : The data binding that prevents the resource to be deleted cannot be changed via the REST API. However the resource can be "freed" via other way as the database from which the data comes from is also accessed by other apps that may change the state of a resource (an SQL DELETE in the DB can always do that).
I'd say 409 is the most appropriate, given it's wording in the RFC:
The 409 (Conflict) status code indicates that the request could not
be completed due to a conflict with the current state of the target
resource. This code is used in situations where the user might be
able to resolve the conflict and resubmit the request. The server
SHOULD generate a payload that includes enough information for a user
to recognize the source of the conflict.
(emphasis mine)
Based on my understanding of the description in the question, the reason for DELETE not being allowed is exactly a conflict with the current state of the target resource. As indicated in the RFC, the response payload can give an indication of the reason and, optionally, the user might be able to resolve it. I don't see anything in the spec that makes 409 inappropriate just because the API doesn't offer a conflict resolution possibility.
A 409 Conflict response is definitely wrong if the client can't resolve the conflict and delete the request later. That is, unless the resource has state tracking whether it can be deleted or not, 409 Conflict is not a good fit.
A 403 Forbidden doesn't necessarily mean not authorized:
However, a request might be forbidden for reasons unrelated to the credentials. -- RFC 7231
The implication is usually there, though. You can use this code, but it may cause some confusion. It'll be especially tricky if the method actually requires authorization also - you'll need a code or something in the response indicating whether the failure was related to authorization or the resource being non-deletable.
I think that 405 Method Not Allowed is the correct way to go.
The 405 (Method Not Allowed) status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource. -- RFC 7231
The method DELETE is not supported for this resource. That sounds exactly like what you're describing. The HTTP spec doesn't really have a concept of a type of resource - just a resource. It happens that people group individual resources under the same endpoint for sanity, but that's just a convenience for developers and users. As far as the HTTP spec is concerned, /widgets/12 and /widgets/15 and /widgets/3453 are three different resources. The fact that the same object represents all three of those resources on the server is completely irrelevant. I think that's the "type" you're thinking of, but to HTTP that's just an implementation detail.