I am working on a Web API service for our Web application (current project). One controller in the Web API will be responsible to retrieve a list of entities of a certain type. So far so good. The problem is that we have a request to filter the list based on search criteria. This search/filter criteria has about a dozen different parameters, some of which can be null. So I figured I create a custom class (let's call it "EntityFilterCriteria") and I instantiate it on the Web application side with whatever filtering fields the user enters (I leave the ones that the user do not enter set to null). Now how do I pass this object to my Web API method? I do not want to build an URL with all parameters because it's going to be a huge URL, plus some parameters may be missing. I can't have a body in the GET HTTP command to serialize my EntityFilterCriteria object so what do I use? POST? It is not really a POST because nothing is updated on the server side. It is really a GET, as in "get me all the records that match this search criteria". What is the common approach in such situations?
Thanks,
Eddie
Serialize the class to JSON and post it to your server, the JSON string will be your post body. Once it is posted you can then deserialize into a class with the same signature. Most languages have either built-in support or free 3rd party modules that can do this for you.
Well the initial danger of using GET for such a request is that the longest url you can send which is guarenteed to work across all web browsers and servers is about 1400 bytes in length.
Personally I would use JSON to encode all of your filter parameters and submit them to the server in the body of a POST command due to the lack of size limit on the sent data.
While there is a semantic difference between GET and POST commands which was intentioned when the HTTP RFC's were written decades ago, those decades of practical use have shifted rather significantly (in the same way that barely anybody uses PUT or DELETE)
I don't see any drawbacks to use a POST method to execute your query and get the result back. For example, ElasticSearch uses this approach to execute queries against the database. See this link for example: http://exploringelasticsearch.com/searching_data.html. In REST, POST isn't necessary used to update data.
Hope it helps.
Thierry
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 have an application of type asp.net mvc and web api.
I m little bit confused over http post and http put.
When to use what and what is the pros and cons of each.
I have gone through many blogs but no solid reason what is designed for what.
Use POST where you would have to create completely new record from scratch.
Use PUT where you would have to update existed record in your database
Here are Differences between PUT & POST
`POST is Not idempotent`-->
Means running POST operation again and again will create new instance everytime when you run call it.
`PUT is Idempotent`-->
PUT is Idempotent operation calling PUT again and again will result same result.
So POST is not idempotent while PUT is idempotent.
`There is also PATCH` -->
Use patch when you would have to update only few properties of your model.In other words Partial Updates.
Put simply (no pun intended):
POST is usually used to CREATE new objects.
PUT is usually used to UPDATE existing objects
Using the correct HTTP verbs allows you to publish a cleaner API and negates the need for encoding intent within the endpoint (url). For example, compare:
Using the correct verbs:
GET api/user/12345
POST api/user/12345
PUT api/user/12345
DELETE api/user/12345
Hacking the endpoint:
GET api/user/12345
POST api/user/12345/create
POST api/user/12345/update
POST api/user/12345/delete
I think the only Cons of using PUT etc are that not all developers are familiar with them and some third party software may not support them or at least it may not be as easy as using the more familiar verbs like GET & POST.
For example, I had a problem a few weeks ago when a proxy was placed in front of an API just before it was to go live and the proxy didn't support the HTTP PUT verb (maybe a config issue - but we didn't have access to the proxy to fix it) so we had to tweak the API and change it to POST at the last minute (which also meant we had to change the clients (mobile apps) that were using it).
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.
In RESTful style programming, we should use HTTP methods as our building blocks. I'm a little confused though which methods match up to the classic CRUD methods. GET/Read and DELETE/Delete are obvious enough.
However, what is the difference between PUT/POST? Do they match one to one with Create and Update?
Create = PUT with a new URI
POST to a base URI returning a newly created URI
Read = GET
Update = PUT with an existing URI
Delete = DELETE
PUT can map to both Create and Update depending on the existence of the URI used with the PUT.
POST maps to Create.
Correction: POST can also map to Update although it's typically used for Create. POST can also be a partial update so we don't need the proposed PATCH method.
The whole key is whether you're doing an idempotent change or not. That is, if taking action on the message twice will result in “the same” thing being there as if it was only done once, you've got an idempotent change and it should be mapped to PUT. If not, it maps to POST. If you never permit the client to synthesize URLs, PUT is pretty close to Update and POST can handle Create just fine, but that's most certainly not the only way to do it; if the client knows that it wants to create /foo/abc and knows what content to put there, it works just fine as a PUT.
The canonical description of a POST is when you're committing to purchasing something: that's an action which nobody wants to repeat without knowing it. By contrast, setting the dispatch address for the order beforehand can be done with PUT just fine: it doesn't matter if you are told to send to 6 Anywhere Dr, Nowhereville once, twice or a hundred times: it's still the same address. Does that mean that it's an update? Could be… It all depends on how you want to write the back-end. (Note that the results might not be identical: you could report back to the user when they last did a PUT as part of the representation of the resource, which would ensure that repeated PUTs do not cause an identical result, but the result would still be “the same” in a functional sense.)
I Was searching for the same answer, here is what IBM say.
IBM Link
POST Creates a new resource.
GET Retrieves a resource.
PUT Updates an existing resource.
DELETE Deletes a resource.
Right now (2016) the latest HTTP verbs are GET, POST, PATCH, PUT and DELETE
Overview
HTTP GET - SELECT/Request
HTTP PUT - UPDATE
HTTP POST - INSERT/Create
HTTP PATCH - When PUTting a complete resource representation is cumbersome and utilizes more bandwidth, e.g.: when you have to update partially a column
HTTP DELETE - DELETE
Hope this helps!
If you are interested on designing REST APIs this is an ansewome reading to have! website online version github repository
There's a great youtube video talk by stormpath with actually explains this, the URL should skip to the correct part of the video:
stormpath youtube video
Also it's worth watch it's over an hour of talking but very intersting if your thinking of investing time in building a REST api.
It depends on the concrete situation.. but in general:
PUT = update or change a concrete resource with a concrete URI of the resource.
POST = create a new resource under the source of the given URI.
I.e.
Edit a blog post:
PUT:
/blog/entry/1
Create a new one:
POST:
/blog/entry
PUT may create a new resource in some circumstances where the URI of the new ressource is clear before the request.
POST can be used to implement several other use cases, too, which are not covered by the others (GET, PUT, DELETE, HEAD, OPTIONS)
The general understanding for CRUD systems is GET = request, POST = create, Put = update, DELETE = delete
The building blocks of REST are mainly the resources (and URI) and the hypermedia. In this context, GET is the way to get a representation of the resource (which can indeed be mapped to a SELECT in CRUD terms).
However, you shouldn't necessarily expect a one-to-one mapping between CRUD operations and HTTP verbs.
The main difference between PUT and POST is about their idempotent property. POST is also more commonly used for partial updates, as PUT generally implies sending a full new representation of the resource.
I'd suggest reading this:
http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
The HTTP specification is also a useful reference:
The PUT method requests that the
enclosed entity be stored under the
supplied Request-URI.
[...]
The fundamental difference between the
POST and PUT requests is reflected in
the different meaning of the
Request-URI. The URI in a POST request
identifies the resource that will
handle the enclosed entity. That
resource might be a data-accepting
process, a gateway to some other
protocol, or a separate entity that
accepts annotations. In contrast, the
URI in a PUT request identifies the
entity enclosed with the request --
the user agent knows what URI is
intended and the server MUST NOT
attempt to apply the request to some
other resource. If the server desires
that the request be applied to a
different URI,
Generally speaking, this is the pattern I use:
HTTP GET - SELECT/Request
HTTP PUT - UPDATE
HTTP POST - INSERT/Create
HTTP DELETE - DELETE
The Symfony project tries to keep its HTTP methods joined up with CRUD methods, and their list associates them as follows:
GET Retrieve the resource from the server
POST Create a resource on the server
PUT Update the resource on the server
DELETE Delete the resource from the server
It's worth noting that, as they say on that page, "In reality, many modern browsers don't support the PUT and DELETE methods."
From what I remember, Symfony "fakes" PUT and DELETE for those browsers that don't support them when generating its forms, in order to try to be as close to using the theoretically-correct HTTP method even when a browser doesn't support it.