Whenever I have to create a RESTful web service and the use case implies on getting data based on a set of search criteria, I always opted for a POST request with the parameters in the body instead of a GET request for all the obvious reasons. I've seen it a dozen of times so I figured is was best practice.
Most recently I stumbled upon this interesting blog article by Evert Pot where he comments on the downsides of the POST verb and simply notes on using the REPORT verb instead. He also states that "its semantics are well defined and it works everywhere".
After reading the post I've been trying to find some more information on this REPORT verb but not much can be found. I know it was part of RFC-3253 as a way to obtain information about a resource but other than that I am clueless.
My question are the following:
Is REPORT really a better alternative than POST in the case of requesting a resource based on a set of search criteria?
Is it wise to start using it or is it too risky? I'm seeing lots of
HTTP Method REPORT not supported issues from various tools and frameworks.
Why does it seem like it is neglected over the years and why do we
know so little about it?
What could other valid use-cases be for using this verb?
Thank you in advance.
The REPORT method is defined in the webdav scope, including the Depth header field, and the DAV:version-tree report request.
Using it outside webdav you may incur in some unspecified behavior.
A REPORT request is an extensible mechanism for obtaining information
about a resource.
This is semantically different from a POST request, where you usually transfer the
expected representation you want to convey to the server.
Consider that in the HTTP method registry REPORT is marked as "safe" and "idempotent", while that's not the case for POST
the value of a report can depend on additional information
specified in the REPORT request body and in the REPORT request
headers.
Those are tied to webdav. To foster REPORT usage we should extend its definition and disentangle it from webdav.
Related
Perhaps a partial duplicate of What is the correct http verb for a Download in a REST API? , though that is referring to a file download specifically.
In terms of CRUD operations, POST is the recommended HTTP verb for creating a resource. Does this still apply to creating resources, even if those resources are not persisted on the server? (i.e. stored in a database or similar) For example, generating some code based on code the client sent or converting a file and returning it to the client.
With such types of functionality, the server has indeed "created" something, though only in passing, returning or streaming it to the client, and not storing it in the traditional CRUD sense. I've always used POST for such functionality, but now I'm starting to double guess myself and think that those could have been GET endpoints the whole time.
Seems like a weird gray area in which neither HTTP verbs GET or POST completely match.
Is POST the correct HTTP verb for resources that are produced by but not stored by the server?
Yes - or alternatively, it's the least incorrect choice to use.
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009
In 2020, the HTTP-WG adopted a proposal to define a method token for "GET with a body", which would give as an alternative to POST when we want to indicate to general purpose components that the request has safe semantics, so there should eventually be some registered method that is a better fit.
There is no gray area here.
If the state of the server changes, use an unsafe method like POST. If it does not, you can use a safe methof like GET, as long as you stay within the documented limitations of GET (no request body).
If you're looking for a safe method that does take a request body, you may want to look at https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/.
Two things:
First, am I correct that an HTTP POST can be used to retrieve existing information? If so, what is the response code?
Second, if POST can be used, what id the format of the URL in a Web.API application, and what data should be sent to the server.
Company security does not prevent using HTTP Get, but they strongly discourage it because of some sort of security issues. OTOH, I really dislike naming a method PostInformation(), when I want to GET existing information.
Thanks
am I correct that an HTTP POST can be used to retrieve existing information?
From RFC 7231, section 4.3.3:
The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.
This implies that the server changes state while not strictly requiring it. So yes, while not really encouraged, this is safe to do. As a matter of fact, many web applications have done so in the past to circumvent limitations of the GET method such as overly long URLs.
what [is] the format of the URL in a Web.API application, and what data should be sent to the server.
The URL would be the same sans the query string. If you mark the body of your request being application/x-www-form-urlencoded, you can fill it with the same string you would normally use for the query string. For more complex or binary data, you should use multipart/formdata (see this answer).
I really dislike naming a method PostInformation(), when I want to GET existing information
That is pretty much a non-issue. I understand your worries, but consider this: What you ultimately do is getting data. How you do so is an implementation detail of the protocol in use. Nothing should prevent you from naming your method PostInformation(). Besides, what were you to do if the implementation changes and you suddenly used GET instead of POST? Refactor all occurences of PostInformation() into GetInformation()?
I'm designing a RESTful service aligning to HATEOAS principles as much as possible. As a result, I need a way to have my cool URLs return a list of links describing available options. I'm using HAL-JSON to facilitate the data format so that's all good, but I'm now considering what HTTP method should pull this.
I'm sure I could stick with a simple GET, but from reading over the HTTP RFC, it seems that OPTIONS might fit the bill here. My only concern is in bold:
9.2 OPTIONS
The OPTIONS method represents a request for information about the
communication options available on the request/response chain
identified by the Request-URI. This method allows the client to
determine the options and/or requirements associated with a resource,
or the capabilities of a server, without implying a resource action or
initiating a resource retrieval.
Responses to this method are not cacheable.
Could someone with more experience on the standards side of the web please explain why this is the case? In my view, you would certainly want clients caching this result at least for a short period of time, as in a fully HATEOAS system this call is likely to be made quite frequently to traverse the rel links to arrive at the operation you're looking for.
I'd also love some opinions on using OPTIONS vs a simple GET for retrieval of operations from a cool URL.
The OPTION HTTP request returns the available methods which can be performed on a resource. (The objects methods)
I can not say for certain why you can not cache the response, but its most likely a precaution. Caching would have little value for the OPTION http method.
A Resource is "any information that can be given a name", that name is its URI. the response from the OPTIONs request is only a list of methods that can be requested on this resource (e.g. "GET PUT POST" maybe the response). To actually get at the information stored, you must use the GET method.
It's not cacheable, period. Sorry.
OK, I know already all the reasons on paper why I should not use a HTTP GET when making a RESTful call to update the state of something on the server. Thus returning possibly different data each time. And I know this is wrong for the following 'on paper' reasons:
HTTP GET calls should be idempotent
N > 0 calls should always GET the same data back
Violates HTTP spec
HTTP GET call is typically read-only
And I am sure there are more reasons. But I need a concrete simple example for justification other than "Well, that violates the HTTP Spec!". ...or at least I am hoping for one. I have also already read the following which are more along the lines of the list above: Does it violate the RESTful when I write stuff to the server on a GET call? &
HTTP POST with URL query parameters -- good idea or not?
For example, can someone justify the above and why it is wrong/bad practice/incorrect to use a HTTP GET say with the following RESTful call
"MyRESTService/GetCurrentRecords?UpdateRecordID=5&AddToTotalAmount=10"
I know it's wrong, but hopefully it will help provide an example to answer my original question. So the above would update recordID = 5 with AddToTotalAmount = 10 and then return the updated records. I know a POST should be used, but let's say I did use a GET.
How exactly and to answer my question does or can this cause an actual problem? Other than all the violations from the above bullet list, how can using a HTTP GET to do the above cause some real issue? Too many times I come into a scenario where I can justify things with "Because the doc said so", but I need justification and a better understanding on this one.
Thanks!
The practical case where you will have a problem is that the HTTP GET is often retried in the event of a failure by the HTTP implementation. So you can in real life get situations where the same GET is received multiple times by the server. If your update is idempotent (which yours is), then there will be no problem, but if it's not idempotent (like adding some value to an amount for example), then you could get multiple (undesired) updates.
HTTP POST is never retried, so you would never have this problem.
If some form of search engine spiders your site it could change your data unintentionally.
This happened in the past with Google's Desktop Search that caused people to lose data because people had implemented delete operations as GETs.
Here is an important reason that GETs should be idempotent and not be used for updating state on the server in regards to Cross Site Request Forgery Attacks. From the book: Professional ASP.NET MVC 3
Idempotent GETs
Big word, for sure — but it’s a simple concept. If an
operation is idempotent, it can be executed multiple times without
changing the result. In general, a good rule of thumb is that you can
prevent a whole class of CSRF attacks by only changing things in your
DB or on your site by using POST. This means Registration, Logout,
Login, and so forth. At the very least, this limits the confused
deputy attacks somewhat.
One more problem is there. If GET method is used , data is sent in the URL itself . In web server's logs , this data gets saved somewhere in the server along with the request path. Now suppose that if someone has access to/reads those log files , your data (can be user id , passwords , key words , tokens etc. ) gets revealed . This is dangerous and has to be taken care of .
In server's log file, headers and body are not logged but request path is . So , in POST method where data is sent in body, not in request path, your data remains safe .
i think that reading this resource:
http://www.servicedesignpatterns.com/WebServiceAPIStyles could be helpful to you to make difference between message API and resource api ?
While reading some articles about writing web servers using Twisted, I came across this page that includes the following statement:
While it's convenient for this example, it's often not a good idea to
make a resource that POSTs to itself; this isn't about Twisted Web,
but the nature of HTTP in general; if you do this, make sure you
understand the possible negative consequences.
In the example discussed in the article, the resource is a web resource retrieved using a GET request.
My question is, what are the possible negative consequences that can arrive from having a resource POST to itself? I am only concerned about the aspects related to the HTTP protocol, so please ignore the fact that I mentioned about Twisted.
The POST verb is used for making a new resource in a collection.
This means that POSTing to a resource has no direct meaning (POST endpoints should always be collections, not resources).
If you want to update your resource, you should PUT to it.
Sometimes, you do not know if you want to update or create the resource (maybe you've created it locally and want to create-or-update it). I think that in that case, the PUT verb is more appropriate because POST really means "I want to create something new".
There's nothing inherently wrong about a page POSTing back to itself - in fact, many of the widely-used frameworks (ASP.NET, etc.) use that method to handle various events that happen on the client - some data is posted back to the same page where the server processes it and sends a new reponse.