They both seem to be sending data to the server inside the body, so what makes them different?
HTTP PUT:
PUT puts a file or resource at a specific URI, and exactly at that URI. If there's already a file or resource at that URI, PUT replaces that file or resource. If there is no file or resource there, PUT creates one. PUT is idempotent, but paradoxically PUT responses are not cacheable.
HTTP 1.1 RFC location for PUT
HTTP POST:
POST sends data to a specific URI and expects the resource at that URI to handle the request. The web server at this point can determine what to do with the data in the context of the specified resource. The POST method is not idempotent, however POST responses are cacheable so long as the server sets the appropriate Cache-Control and Expires headers.
The official HTTP RFC specifies POST to be:
Annotation of existing resources;
Posting a message to a bulletin board, newsgroup, mailing list,
or similar group of articles;
Providing a block of data, such as the result of submitting a
form, to a data-handling process;
Extending a database through an append operation.
HTTP 1.1 RFC location for POST
Difference between POST and PUT:
The RFC itself explains the core difference:
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, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make
its own decision regarding whether or not to redirect the request.
Additionally, and a bit more concisely, RFC 7231 Section 4.3.4 PUT states (emphasis added),
4.3.4. PUT
The PUT method requests that the state of the target resource be
created or replaced with the state defined by the representation
enclosed in the request message payload.
Using the right method, unrelated aside:
One benefit of REST ROA vs SOAP is that when using HTTP REST ROA, it encourages the proper usage of the HTTP verbs/methods. So for example you would only use PUT when you want to create a resource at that exact location. And you would never use GET to create or modify a resource.
Only semantics.
An HTTP PUT is supposed to accept the body of the request, and then store that at the resource identified by the URI.
An HTTP POST is more general. It is supposed to initiate an action on the server. That action could be to store the request body at the resource identified by the URI, or it could be a different URI, or it could be a different action.
PUT is like a file upload. A put to a URI affects exactly that URI. A POST to a URI could have any effect at all.
To give examples of REST-style resources:
POST /books with a bunch of book information might create a new book, and respond with the new URL identifying that book: /books/5.
PUT /books/5 would have to either create a new book with the ID of 5, or replace the existing book with ID 5.
In non-resource style, POST can be used for just about anything that has a side effect. One other difference is that PUT should be idempotent: multiple PUTs of the same data to the same URL should be fine, whereas multiple POSTs might create multiple objects or whatever it is your POST action does.
GET: Retrieves data from the server. Should have no other effect.
PUT: Replaces target resource with the request payload. Can be used to update or create a new resource.
PATCH: Similar to PUT, but used to update only certain fields within an existing resource.
POST: Performs resource-specific processing on the payload. Can be used for different actions including creating a new resource, uploading a file, or submitting a web form.
DELETE: Removes data from the server.
TRACE: Provides a way to test what the server receives. It simply returns what was sent.
OPTIONS: Allows a client to get information about the request methods supported by a service. The relevant response header is Allow with supported methods. Also used in CORS as preflight request to inform the server about actual the request method and ask about custom headers.
HEAD: Returns only the response headers.
CONNECT: Used by the browser when it knows it talks to a proxy and the final URI begins with https://. The intent of CONNECT is to allow end-to-end encrypted TLS sessions, so the data is unreadable to a proxy.
PUT is meant as a a method for "uploading" stuff to a particular URI, or overwriting what is already in that URI.
POST, on the other hand, is a way of submitting data RELATED to a given URI.
Refer to the HTTP RFC
As far as i know, PUT is mostly used for update the records.
POST - To create document or any other resource
PUT - To update the created document or any other resource.
But to be clear on that PUT usually 'Replaces' the existing record if it is there and creates if it not there..
Define operations in terms of HTTP methods
The HTTP protocol defines a number of methods that assign semantic meaning to a request. The common HTTP methods used by most RESTful web APIs are:
GET retrieves a representation of the resource at the specified URI. The body of the response message contains the details of the requested resource.
POST creates a new resource at the specified URI. The body of the request message provides the details of the new resource. Note that POST can also be used to trigger operations that don't actually create resources.
PUT either creates or replaces the resource at the specified URI. The body of the request message specifies the resource to be created or updated.
PATCH performs a partial update of a resource. The request body specifies the set of changes to apply to the resource.
DELETE removes the resource at the specified URI.
The effect of a specific request should depend on whether the resource is a collection or an individual item. The following table summarizes the common conventions adopted by most RESTful implementations using the e-commerce example. Not all of these requests might be implemented—it depends on the specific scenario.
Resource
POST
GET
PUT
DELETE
/customers
Create a new customer
Retrieve all customers
Bulk update of customers
Remove all customers
/customers/1
Error
Retrieve the details for customer 1
Update the details of customer 1 if it exists
Remove customer 1
/customers/1/orders
Create a new order for customer 1
Retrieve all orders for customer 1
Bulk update of orders for customer 1
Remove all orders for customer 1
The differences between POST, PUT, and PATCH can be confusing.
A POST request creates a resource. The server assigns a URI for the new resource and returns that URI to the client. In the REST model, you frequently apply POST requests to collections. The new resource is added to the collection. A POST request can also be used to submit data for processing to an existing resource, without any new resource being created.
A PUT request creates a resource or updates an existing resource. The client specifies the URI for the resource. The request body contains a complete representation of the resource. If a resource with this URI already exists, it is replaced. Otherwise, a new resource is created, if the server supports doing so. PUT requests are most frequently applied to resources that are individual items, such as a specific customer, rather than collections. A server might support updates but not creation via PUT. Whether to support creation via PUT depends on whether the client can meaningfully assign a URI to a resource before it exists. If not, then use POST to create resources and PUT or PATCH to update.
A PATCH request performs a partial update to an existing resource. The client specifies the URI for the resource. The request body specifies a set of changes to apply to the resource. This can be more efficient than using PUT, because the client only sends the changes, not the entire representation of the resource. Technically PATCH can also create a new resource (by specifying a set of updates to a "null" resource), if the server supports this.
PUT requests must be idempotent. If a client submits the same PUT request multiple times, the results should always be the same (the same resource will be modified with the same values). POST and PATCH requests are not guaranteed to be idempotent.
Please see: http://zacharyvoase.com/2009/07/03/http-post-put-diff/
I’ve been getting pretty annoyed lately by a popular misconception by web developers that a POST is used to create a resource, and a PUT is used to update/change one.
If you take a look at page 55 of RFC 2616 (“Hypertext Transfer Protocol – HTTP/1.1”), Section 9.6 (“PUT”), you’ll see what PUT is actually for:
The PUT method requests that the enclosed entity be stored under the supplied Request-URI.
There’s also a handy paragraph to explain the difference between POST and PUT:
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.
It doesn’t mention anything about the difference between updating/creating, because that’s not what it’s about. It’s about the difference between this:
obj.set_attribute(value) # A POST request.
And this:
obj.attribute = value # A PUT request.
So please, stop the spread of this popular misconception. Read your RFCs.
Others have already posted excellent answers, I just wanted to add that with most languages, frameworks, and use cases you'll be dealing with POST much, much more often than PUT. To the point where PUT, DELETE, etc. are basically trivia questions.
A POST is considered something of a factory type method. You include data with it to create what you want and whatever is on the other end knows what to do with it. A PUT is used to update existing data at a given URL, or to create something new when you know what the URI is going to be and it doesn't already exist (as opposed to a POST which will create something and return a URL to it if necessary).
It should be pretty straightforward when to use one or the other, but complex wordings are a source of confusion for many of us.
When to use them:
Use PUT when you want to modify a singular resource that is already a part of resource collection. PUT replaces the resource in its entirety. Example: PUT /resources/:resourceId
Sidenote: Use PATCH if you want to update a part of the resource.
Use POST when you want to add a child resource under a collection of resources.
Example: POST => /resources
In general:
Generally, in practice, always use PUT for UPDATE operations.
Always use POST for CREATE operations.
Example:
GET /company/reports => Get all reports
GET /company/reports/{id} => Get the report information identified by "id"
POST /company/reports => Create a new report
PUT /company/reports/{id} => Update the report information identified by "id"
PATCH /company/reports/{id} => Update a part of the report information identified by "id"
DELETE /company/reports/{id} => Delete report by "id"
The difference between POST and PUT is that PUT is idempotent, that means, calling the same PUT request multiple times will always produce the same result(that is no side effect), while on the other hand, calling a POST request repeatedly may have (additional) side effects of creating the same resource multiple times.
GET : Requests using GET only retrieve data , that is it requests a representation of the specified resource
POST : It sends data to the server to create a resource. The type of the body of the request is indicated by the Content-Type header. It often causes a change in state or side effects on the server
PUT : Creates a new resource or replaces a representation of the target resource with the request payload
PATCH : It is used to apply partial modifications to a resource
DELETE : It deletes the specified resource
TRACE : It performs a message loop-back test along the path to the target resource, providing a useful debugging mechanism
OPTIONS : It is used to describe the communication options for the target resource, the client can specify a URL for the OPTIONS method, or an asterisk (*) to refer to the entire server.
HEAD : It asks for a response identical to that of a GET request, but without the response body
CONNECT : It establishes a tunnel to the server identified by the target resource , can be used to access websites that use SSL (HTTPS)
In simple words you can say:
1.HTTP Get:It is used to get one or more items
2.HTTP Post:It is used to create an item
3.HTTP Put:It is used to update an item
4.HTTP Patch:It is used to partially update an item
5.HTTP Delete:It is used to delete an item
It would be worth mentioning that POST is subject to some common Cross-Site Request Forgery (CSRF) attacks while PUT isn't.
The CSRF below are not possible with PUT when the victim visits attackersite.com.
The effect of the attack is that the victim unintentionally deletes a user just because it (the victim) was logged-in as admin on target.site.com, before visiting attackersite.com:
Malicious code on attackersite.com:
Case 1: Normal request. saved target.site.com cookies will automatically be sent by the browser: (note: supporting PUT only, at the endpoint, is safer because it is not a supported <form> attribute value)
<!--deletes user with id 5-->
<form id="myform" method="post" action="http://target.site.com/deleteUser" >
<input type="hidden" name="userId" value="5">
</form>
<script>document.createElement('form').submit.call(document.getElementById('myform'));</script>
Case 2: XHR request. saved target.site.com cookies will automatically be sent by the browser: (note: supporting PUT only, at the endpoint, is safer because an attempt to send PUT would trigger a preflight request, whose response would prevent the browser from requesting the deleteUser page)
//deletes user with id 5
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://target.site.com/deleteUser");
xhr.withCredentials=true;
xhr.send(["userId=5"]);
MDN Ref : [..]Unlike “simple requests” (discussed above), --[[ Means: POST/GET/HEAD ]]--, for "preflighted" requests the browser first sends an HTTP request using the OPTIONS method[..]
cors in action : [..]Certain types of requests, such as DELETE or PUT, need to go a step further and ask for the server’s permission before making the actual request[..]what is called a preflight request[..]
REST-ful usage
POST is used to create a new resource and then returns the resource URI
EX
REQUEST : POST ..../books
{
"book":"booName",
"author":"authorName"
}
This call may create a new book and returns that book URI
Response ...THE-NEW-RESOURCE-URI/books/5
PUT is used to replace a resource, if that resource is exist then simply update it, but if that resource doesn't exist then create it,
REQUEST : PUT ..../books/5
{
"book":"booName",
"author":"authorName"
}
With PUT we know the resource identifier, but POST will return the new resource identifier
Non REST-ful usage
POST is used to initiate an action on the server side, this action may or may not create a resource, but this action will have side affects always it will change something on the server
PUT is used to place or replace literal content at a specific URL
Another difference in both REST-ful and non REST-ful styles
POST is Non-Idempotent Operation: It will cause some changes if executed multiple times with the same request.
PUT is Idempotent Operation: It will have no side-effects if executed multiple times with the same request.
Actually there's no difference other than their title. There's actually a basic difference between GET and the others. With a "GET"-Request method, you send the data in the url-address-line, which are separated first by a question-mark, and then with a & sign.
But with a "POST"-request method, you can't pass data through the url, but you have to pass the data as an object in the so called "body" of the request. On the server side, you have then to read out the body of the received content in order to get the sent data.
But there's on the other side no possibility to send content in the body, when you send a "GET"-Request.
The claim, that "GET" is only for getting data and "POST" is for posting data, is absolutely wrong. Noone can prevent you from creating new content, deleting existing content, editing existing content or do whatever in the backend, based on the data, that is sent by the "GET" request or by the "POST" request. And nobody can prevent you to code the backend in a way, that with a "POST"-Request, the client asks for some data.
With a request, no matter which method you use, you call a URL and send or don't send some data to specify, which information you want to pass to the server to deal with your request, and then the client gets an answer from the server. The data can contain whatever you want to send, the backend is allowed to do whatever it wants with the data and the response can contain any information, that you want to put in there.
There are only these two BASIC METHODS. GET and POST. But it's their structure, which makes them different and not what you code in the backend. In the backend you can code whatever you want to, with the received data. But with the "POST"-request you have to send/retrieve the data in the body and not in the url-addressline, and with a "GET" request, you have to send/retrieve data in the url-addressline and not in the body. That's all.
All the other methods, like "PUT", "DELETE" and so on, they have the same structure as "POST".
The POST Method is mainly used, if you want to hide the content somewhat, because whatever you write in the url-addressline, this will be saved in the cache and a GET-Method is the same as writing a url-addressline with data. So if you want to send sensitive data, which is not always necessarily username and password, but for example some ids or hashes, which you don't want to be shown in the url-address-line, then you should use the POST method.
Also the URL-Addressline's length is limited to 1024 symbols, whereas the "POST"-Method is not restricted. So if you have a bigger amount of data, you might not be able to send it with a GET-Request, but you'll need to use the POST-Request. So this is also another plus point for the POST-request.
But dealing with the GET-request is way easier, when you don't have complicated text to send.
Otherwise, and this is another plus point for the POST method, is, that with the GET-method you need to url-encode the text, in order to be able to send some symbols within the text or even spaces. But with a POST method you have no restrictions and your content doesn't need to be changed or manipulated in any way.
Summary
Use PUT to create or replace the state of the target resource with the state defined by the representation enclosed in the request. That standardized intended effect is idempotent so it informs intermediaries that they can repeat a request in case of communication failure.
Use POST otherwise (including to create or replace the state of a resource other than the target resource). Its intended effect is not standardized so intermediaries cannot rely on any universal property.
References
The latest authoritative description of the semantic difference between the POST and PUT request methods is given in RFC 7231 (Roy Fielding, Julian Reschke, 2014):
The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation. The target resource in a POST request is intended to handle the enclosed representation according to the resource's own semantics, whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. Hence, the intent of PUT is idempotent and visible to intermediaries, even though the exact effect is only known by the origin server.
In other words, the intended effect of PUT is standardized (create or replace the state of the target resource with the state defined by the representation enclosed in the request) and so is common to all target resources, while the intended effect of POST is not standardized and so is specific to each target resource. Thus POST can be used for anything, including for achieving the intended effects of PUT and other request methods (GET, HEAD, DELETE, CONNECT, OPTIONS, and TRACE).
But it is recommended to always use the more specialized request method rather than POST when applicable because it provides more information to intermediaries for automating information retrieval (since GET, HEAD, OPTIONS, and TRACE are defined as safe), handling communication failure (since GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are defined as idempotent), and optimizing cache performance (since GET and HEAD are defined as cacheable), as explained in It Is Okay to Use POST (Roy Fielding, 2009):
POST only becomes an issue when it is used in a situation for which some other method is ideally suited: e.g., retrieval of information that should be a representation of some resource (GET), complete replacement of a representation (PUT), or any of the other standardized methods that tell intermediaries something more valuable than “this may change something.” The other methods are more valuable to intermediaries because they say something about how failures can be automatically handled and how intermediate caches can optimize their behavior. POST does not have those characteristics, but that doesn’t mean we can live without it. POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.”
Both PUT and POST are Rest Methods .
PUT - If we make the same request twice using PUT using same parameters both times, the second request will not have any effect. This is why PUT is generally used for the Update scenario,calling Update more than once with the same parameters doesn't do anything more than the initial call hence PUT is idempotent.
POST is not idempotent , for instance Create will create two separate entries into the target hence it is not idempotent so CREATE is used widely in POST.
Making the same call using POST with same parameters each time will cause two different things to happen, hence why POST is commonly used for the Create scenario
Post and Put are mainly used for post the data and other update the data. But you can do the same with post request only.
We have a REST API that reads and deletes the record from database and returns the read value back to the client, all in same call. We have exposed it using HTTP POST. Should this be exposed as HTTP GET? What will be the implications in terms of Caching in case we expose it as GET.
First, you should keep in mind that one of the reasons that we care that a request is safe or idempotent is that the network is unreliable. Some non zero number of responses to the query are going to be lost, and what do you want to do about that?
A protocol where the client uses GET to request the resource, and then DELETE to acknowledge receipt, may be a more reliable choice than burning the resource on a single response.
Should this be exposed as HTTP GET?
Perhaps. I would not be overly concerned with the fact that the the second GET returns a different response than the first. Safe/idempotent doesn't promise that the response will be the same every time, it just promises that the second request doesn't change the effects.
DELETE, for example, is idempotent, because deleting something twice is the same as deleting it once, even though you might return 200 to the first request and 404/410 to the second.
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 (money, BTW, is considered property for the
sake of this definition).
I think the thing to pay attention to here is "loss of property". What kind of damage does it cause if generic components think that GET means GET? and act accordingly (for example, by pre-fetching the resource, or by crawling the API).
But you definitely need to be thinking about the semantics -- are we reading the document, and the delete of the database record is a side effect? or are we deleting the record, and receiving a last known representation as the response?
POST, of course, is also fine -- POST can mean anything.
What will be the implications in terms of Caching in case we expose it as GET.
RFC 7234 - I don't believe there are any particularly unusual implications. You should be able to get the caching behavior you want by specifying the appropriate headers.
If I'm interpreting your use case correctly, then you may want to include a private directive, for example.
As per the above discussion, it looks like PUT request. You should not use GET as it is idempotent because the same data is not available for the second time call. POST is used to create a new resource. So it will be better to use PUT http method for this kind of requirement. Refer below the link for more details.
https://restfulapi.net/http-methods/
I just want to know the high level steps of the process. Here's my thought on the process:
Assumption: the API returns JSON format
Check the API document to see the structure of the returned JSON
Create a corresponding Java class (ex: Employee)
Make Http call to the endpoint to get the JSON response
Using some JSON library (such as GSON, Jackson) to unmarshall the JSON string to Employee object.
Manipulate the Employee object
However, what if the API returned JSON is changed? it's really tedious task to exam the JSON string every now and then to adjust the corresponding Java class.
Can anyone help me out with this understanding. Thanks
You describe how to consume a json over http API, which is fine since most of the APIs out there are just that. If you are interested in consuming Restful HTTP resources however, one way would be:
Check the API documentation, aka. the media-types that your client will need to support in order to communicate with its resources. Some RESTafarians argue that all media-types should be standardized, so all clients could potentially support them, but I think that goes a bit far.
Watch out for link representations, and processing logic. media-types do not only describe the format of the data, but also how to process them. How to display it if its an image, how to run code that might be part of the message, how to layout onto the screen, how to use embedded controls like forms, etc.
Create corresponding Java classes. If the resources "only" describe data (which they usually do in API context), then simple Java classes will do, otherwise more might be needed. For example: can the representation contain JavaScript to run on the client? You need to embed a JavaScript engine, and prepare your class to do just that.
Make call to a bookmarked URI if you have it. There should be no hardcoded SOAP-like "endpoint" you call. You start with bookmarks and work your way to the state your client need to be in.
Usually your first call goes to the "start" resource. This is the only bookmark you have in the beginning. You specify the media-types you support for this resource in the Accept header.
You then check whether the returned Content-Type matches one of your accepted media-types (remember, the server is free to ignore your preferences), and then you process the returned representation according to its rules.
For example you want to get all the accounts for customer 123456 for which you don't yet have a bookmark to. You might first GET the start resource for account management. The processing logic there might describe a link to go to for account listings. You follow the link. The representation there might give you a "form" in which you have to fill out the customer number and POST. Finally, you get your representation of the account list. You may at this point bookmark the page, so you don't have to go through the whole chain the next time.
Process representation. This might involve displaying, running, or just handing over the data to some other class.
Sorry for the long post, slow day at work :) Just for completeness, some other points the client needs to know about: caching, handling bookmarks (reacting to 3xx codes), following links in representations.
Versioning is another topic you mention. This is a whole discussion onto itself, but in short: some people (myself included) advocate versioning the media-type. Non-backwards compatible changes simply change the media type's name (for example from application/vnd.company.customer-v1+json, to application/vnd.company.customer-v2+json), and then everything (bookmarks for example) continues to work because of content negotiation.
There are many ways to consume RESTful APIs.
Typically, you need to know what version of the API you are going to use. When the API changes (i.e. a different version is exposed) you need to decide if the new functionality is worth migrating your application(s) to the latest and greatest or not...
In my experience, migrating to a new API always requires some effort and it really depends on the value of doing so (vs. not doing it) and/or whether the old API is going to be deprecated and/or not supported by the publisher.