Even after reading many documents, books, spec
I couldn't 100% be certain whether I should use http status code 403 or 409 in my case.
Some argue that 403 should be used only with an authorization issue, but seeing twitter's api using 403 for update limits violation, I think 403 actual use is broader than just authorization issues. Maybe it can be used to tell a request has violated a server-side constraint.
And, from the spec, 409 seems to be used when we can expect that client can resolve the issue.
I'd appreciate some variety of real world examples of when to use 403 and when to use 409, and for an opinion on which code to use in my case, which I will lay out in the abstract below (so as not to violate NDA).
After edit: The example is lengthy but, simply put, it is about what code to return when constraint validation fails. Do you always return 400 when constraint validation fails? Should I return 400 and not 403 or 409?
There is a client that tells service A which shelf contains a specific book. While recording to the DB which book is on which shelf, service A is able to tell the client that the client is trying to put the book in a wrong shelf. Service A can tell this by asking another service B that basically has some logic in deciding where a book should go to.
What http code should service A use in this case?
(The request conflicts with service B's decision -- 409? -- but the client is not able to resolve this problem because when service B makes a decision it is permanent. And book id and bookshelf id is both in the path parameter (ie, they are the only parameters in this endpoint) so the client can't really make any change to resolve the issue with the same request)
Additionally, the client is able to tell service A that a bookshelf should no longer be used (because it is full or for whatever reason). When the client tells service A that bookshelf C is not in use anymore, and then later the client tells service A that it wants to put another book on bookshelf C, service A should tell the client that it can't do that. What http code should service A use in this case? (The request will conflict the database status that says bookshelf C is not in use -- 409? But client is not able to resolve this problem because when a bookshelf is not in use, it is permanent in service A and it is never in use again -- not 409?)
Thank you in advance for your time and input!
Of the two codes mentioned, HTTP 403 is far more common and describes a valid (but unauthorized) request
HTTP 409 is not very common. It describes a conflict (like a deadlock or some other type of issue) that resulted in an error. I think Mozilla gives good advice when it describes this error most commonly occurring with with the PUT verb.
For a broader error condition, I would recommend using a 500 error code
Related
I know the use of http verbs is based on standard specification. But my question if I use "GET" for update operations and write a code logic to update, does it create issues in any scenario? Apart from the standard, what else could be the reason to use these verbs for a specific purpose only?
my question if I use "GET" for update operations and write a code logic to update, does it create issues in any scenario?
Yes.
A simple example - suppose the network between the client and the server is unreliable; specifically, for a time, HTTP responses are being lost. A general purpose component (like a web proxy) might time out, and then, noticing that the method token of the request is GET, resend the request a second/third/fourth time, with your server performing its update on every GET request.
Let us further assume that these multiple update operations lead to an undesirable outcome; where do we properly affix blame?
Second example: you send someone a copy of the link to the update operation, so that they can send you a request at the appropriate time. But suppose you send that link to them in an email, and the email client recognizes the uri and (as a performance optimization) pre-fetches the link, triggering your update operation too early. Where do we properly affix the blame?
HTTP does not attempt to require the results of a GET to be safe. What it does is require that the semantics of the operation be safe, and therefore it is a fault of the implementation, not the interface or the user of that interface, if anything happens as a result that causes loss of property -- Fielding, 2002
In these, and other examples, blame is correctly affixed to your server, because GET has a standardized meaning which include the constraint that the semantics of the request are safe.
That's not to say that you can't have side effects when handling a GET request; "hit counters" are almost as old as the web itself. You have a lot of freedom in your implementation; so long as you respect the uniform interface, there won't be too much trouble.
Experience report: one of our internal tools uses GET requests to trigger scheduling; in our carefully controlled context (which is not web scale), we get away with it, and have for a very long time.
To borrow your language, there are certainly scenarios that would give us problems; but given our controls we manage to avoid them.
I wouldn't like our chances, though, if requests started coming in from outside of our carefully controlled context.
I think it's a decent question. You're asking a hypothetical: is there any value to doing the right other than that's we agree to use GET for fetching? e.g.: is there value beyond the fact that it's 'semantically nice'. A similar question in HTML might be: "Is it ok to use a <div> with an onclick instead of a <button>? (the answer is no).
There certainly is. Clients, servers and intermediates all change their behavior depending on what method is used. Even if your server can process GET for updates, and you build a client that uses this, your browser might still get confused.
If you are interested in this subject, don't ask on a forum; read the spec. The HTTP specification tells you what clients, servers and proxies should do when they encounter certain methods, statuses and headers.
Start at RFC7231
In REST Web Services we have GET AND DELETE methods.
Generally we read GET is to get data from server like "getCountriesName" and DELETE is used to call resource which deletes particular object like "removeOrganization".
But if i implements DELETE to "getCountriesName" then it successfully returns country name.
So how both are different? Any real-time scenario?
It is technically possible, but if you make that way, then you are not following the REST standards. I would recommend to use delete to remove resources and get to query them
Looking at the Richardson Maturity Model, if you're aiming to achieve at least level 2 of REST, you'll end up with resources (Country) and HTTP VERBS:
GET /api/countries/{id}
which would also return the country's name, among other parameters.
You could also issue a DELETE request towards the same URL, provided there's an endpoint that supports this - in the backend you'll usually have methods that allow a certain HTTP VERB on them. The details of the implementation depend on the language you're using, for example in C# you would have a method with mostly the same signature, but a different attribute on top of it, like [HttpDelete]).
Thinking in terms of methods (getCountriesName/removeOrganization) is not RESTful at all, but rather SOAP/RPC.
How your service handles requests is completely up to you. You could basically create new resources on receiving GET requests or delete things using OPTION, though I highly recommend to not do so as this does not adhere to the backing protocol (HTTP in this specific case) and thus violates a basic REST constraints. Note further that a RESTful service should always adhere to and respect the supported protocols.
According to RFC 7231, one of the major differences between GET and DELETE is, that the latter one removes an association from a given resource and its functionality and also that the returned response is not cachable. This may or may not remove the data physically, the effect on consecutive DELETE or GET operations is, however, that the deleted resource should not be obtainable further. A consecutive DELETE request is issued to the server regardless of any previous request. If the resource was deleted before, the service should notify the client with a propper 404 Not Found error response if no new resource was created in between two delete operations on the same resource.
GET responses, on the other side, are cachable and thus may save work on the server by returning the result from a previous request directly from the (proxied) cache rather then issuing the request to the server. This can be fine-grained with propper cache-header settings.
The type of HTTP method to be used is more of a convention and a practice to be followed. This would give wrong information when the API s are exposed to the external systems
Refer to the blog post for detailed info
I don't quite get how the HTTP verbs are defined as idempotent. All I've read is GET and PUT is idempotent. POST is not idempotent. But you could create a REST API using POST that doesn't change anything (in the database for example), or create a REST API for PUT that changes every time it is called.
Sure, that probably is the wrong way to do things but if it can be done, why is PUT labeled as idempotent (or POST as not) when it is up to the implementation? I'm not challenging this idea, I'm probably missing something and I ask to clear my understanding.
EDIT:
I guess one way to put my question is: What would be the problem if I used PUT to make a non-idempotent call and POST to do so?
You are right in pointing out there is nothing inherent within the HTTP protocol that enforces the idempotent attribute of methods/verbs like PUT and DELETE. HTTP, being a stateless protocol, retains no information or status of each request that the user makes; every single request is treated as independent.
To quote Wikipedia on the idempotent attribute of HTTP methods (emphasis mine):
Note that whether a method is idempotent is not enforced by the
protocol or web server. It is perfectly possible to write a web
application in which (for example) a database insert or other
non-idempotent action is triggered by a GET or other request. Ignoring
this recommendation, however, may result in undesirable consequences,
if a user agent assumes that repeating the same request is safe when
it isn't.
So yes, it is possible to deviate from conventional implementation, and rollout things like non-changing POST implementation, non-idempotent PUT etc. probably with no significant, life-threatening technical problems. But you might risk upsetting other programmers consuming your web services, thinking that you don't know what you're doing.
Here's an important quote from RFC2616 on the HTTP methods being safe (emphasis mine):
Implementors should be aware that the software represents the user in
their interactions over the Internet, and should be careful to allow
the user to be aware of any actions they might take which may have an
unexpected significance to themselves or others.
In particular, the convention has been established that the GET and
HEAD methods SHOULD NOT have the significance of taking an action
other than retrieval. These methods ought to be considered "safe".
This allows user agents to represent other methods, such as POST, PUT
and DELETE, in a special way, so that the user is made aware of the
fact that a possibly unsafe action is being requested.
Naturally, it is not possible to ensure that the server does not
generate side-effects as a result of performing a GET request; in
fact, some dynamic resources consider that a feature. The important
distinction here is that the user did not request the side-effects, so
therefore cannot be held accountable for them.
UPDATE: As pointed out by Julian, RFC 2616 has been replaced by RFC 7231. Here's the corresponding section.
So when you publish a web service as a PUT method, and I submit a request that looks like:
PUT /users/<new_id> HTTP/1.1
Host: example.com
I will expect a new user resource to be created. Likewise, if my request looks like:
PUT /users/<existing_id> HTTP/1.1
Host: example.com
I will expect the corresponding existing user to be updated. If I repeat the same request by submitting the form multiple times, please don't pop up a warning dialog (because I like the established convention).
Conversely, as a consumer of a POST web service, I will expect requests like:
POST /users/<existing_id> HTTP/1.1
Host: example.com
to update the corresponding existing user, while a request that looks like:
POST /users/<new_id> HTTP/1.1
Host: example.com
to raise an error because the URL doesn't exist yet.
Indeed, an implementation can do anything it wants. However, if that is incorrect according to the protocol spec, surprising things might happen (such as as library or intermediary repeating a PUT if this first attempt failed).
hope the link helps to you:HTTP Method idempotency
Be careful when dealing with safe methods as well: if a seemingly safe method like GET will change a resource, it might be possible that any middleware client proxy systems between you and the server, will cache this response. Another client who wants to change this resource through the same URL(like: http://example.org/api/article/1234/delete), will not call the server, but return the information directly from the cache. Non-safe (and non-idempotent) methods will never be cached by any middleware proxies.
I don't see a huge benefit of designing a REST API service that uses PUT and DELETE to update and delete data. These 2 verbs can be easily replaced by using a POST and a unique url.
The only benefit I see of using PUT and DELETE is it cuts down the number of url's that the REST API service uses which isn't much. Are there other benefits that I'm overlooking?
This actually has not so much to do with REST, but more with the Hypertext Transfer Protocol (HTTP).
The basic idea of HTTP is that you perform a certain action (one of the HTTP methods, such as GET, POST, PUT and DELETE) on a certain resource (identified by its URL). So if you start deviating from that by adding the action into the URL (such as http://example.com/api/books/123/delete) and using a different HTTP method, you are violating the HTTP protocol.
The downsides of this might not be instantly visible (because it will still work), and might be limited if you are only using the API by yourself. However, if other programmers are using the API as well, you are creating certain expectations by stating that you have a RESTful HTTP API while you are actually not adhering to the protocol.
For instance, if calling GET /api/books/123 returns a representation of the book resource, a developer expects to be able to call PUT on that same URL to update the information on that book, and DELETE to remove the book alltogether. (of course, if he does not have permissions to do that, you don't actually remove the book but you return a 403 'Forbidden' or 405 'Method Not Allowed' status code - which are also part of the HTTP specification)
However, if you deviate from the protocol (basically inventing your own protocol), you will have to describe somewhere that instead of calling DELETE /api/books/123 developers have to call POST /api/books/123/remove/the/book. They will have to be aware of all your API's custom rules because you are not following the standard.
Another good point is made by Darrel Miller in his answer. The HTTP methods all have a certain meaning and also certain characteristics. For instance, GET is supposed to be a safe method, used to retrieve information without making any changes on the server side. And PUT and DELETE are idempotent, which means that (even though they are not safe methods like GET) you can make as many requests as you like without any unwanted side effects (deleting a book one or ten times has the same effect: the book is gone). POST however is not idempotent: if you do ten POST requests to create a new book, you will most likely end up with 10 duplicate book entries.
Because of these characteristics, developers and tools are able to make certain assumptions. For instance, a search indexer such as Googlebot will only do GET requests, in order to not break anything on the server. However, if you would be violating the HTTP specification by having a URL http://example.com/api/books/123/delete in order to delete a book, you might notice at one day that your database is completely empty because Google has been indexing your site. That wouldn't be Google's fault but yours, because you didn't follow the specification.
So to make a long story short: using a protocol or standard (such as HTTP) sets certain expectations, and if you then deviate from the protocol you will create unexpected behavior and possible unwanted side effects.
It is not required to use PUT and DELETE to get the benefits of a REST based system.
Using the more precise methods can be advantageous in certain cases. Usually it is intermediary components that take advantage of the semantics. PUT and DELETE are idempotent methods, so if some generic component receives a 503, in theory it could retry a PUT/DELETE until it gets a successful response. With a POST method, the intermediary can't do that.
With a DELETE method a client knows not to send a body. With a PUT, it knows to send a complete representation. With a POST method, you need to communicate to the client how to make the request in some other way, like a link relation.
You can live without PUT and DELETE.
This article tells you why: http://www.artima.com/lejava/articles/why_put_and_delete.html
..BUT (quote from Fielding): "A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field. Workarounds for broken implementations (such as those browsers stupid enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least in appendices, with an expectation that the workaround will eventually be obsolete. [Failure here implies that the resource interfaces are object-specific, not generic.] "
(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven)
I'm making some REST services, and as I'm implementing a GET request, I was debating about what I should do if there is no record there, for example /profile/1234. Now, if you tried to use /profiles/1234 (note the s on profiles) it would definitely be a 404 code because that URL definitely isn't found. But when it comes to there just being no 1234 profile, I'm not sure what I should return. I don't want to return {} because that might give the impression there is a record with no data. But if I return a 404 error code, how is the consumer of the API supposed to tell the difference between the two 404s?
How can I be a responsible API designer by communicating programmatically what the difference between a service that doesn't exist and a record that doesn't exist?
You can send a custom status message which will help you differentiate between the "different" 404s.
On the other hand, I wouldn't worry about that distinction. People are used to having to type api endpoints carefully. As long as they manually test their app a tiny bit the issue becomes a non-issue.