What is a PUT request?
In the words of the RFC2616 memo: "The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response."
The PUT method modifies an existing resource or creates a new resource, and does so in an idempotent manner, which differentiates it from POST.
PUT Request Tutorial
Let's say you change your email address in your Spotify profile. When you update the existing record, this is a PUT request.
A PUT request might look like this: `PUT https://www.abstractapi.com/users/{{userID}}`. This would send data to the `/users/{{userID}}` endpoint, and update that user's information, and if there is no content at that resource URI, create a new record.
The successful response should be HTTP status code `200 OK` or `201 (created)` (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT).
What is a POST request?
In the words of the RFC2616 memo: "the POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. It essentially means that POST request-URI should be of a collection URI."
POST Request Example
A POST request sends data to an API, either creating or updating an existing resource. POST is like a contact form on a website. When you fill out the form and hit Send, that data is put in the body of the request and sent to the server. This may be JSON, XML, or query parameters.
A POST request might look like this: `POST https://www.abstractapi.com/users/{{userID}}`. This would send data to the `/users/{{userID}}` endpoint, and either update that user's information or create a new user account.
The response SHOULD be HTTP response code `201`, but sometimes the action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either HTTP status code `200` (OK) or `204` (No Content) is the appropriate response status.
PUT vs POST Requests
We use PUT and POST for different situations, depending on idempotency. If a request is idempotent, calling it once or several times successively has the same effect. If the request is non-idempotent, each successive request will act on the previous request, causing potential problems.
The difference between PUT and POST is that PUT is idempotent: calling it once or several times successively has the same effect, whereas successive identical POST requests may have additional effects, akin to placing an order several times.
PUT is like a file upload. It puts information in the universal resource identifier (URI), and that's all it does. A POST request can do this too (non-idempotently), and creates new files.
Conclusion
PUT and POST are similar in that they are both REST API requests, and they both modify data, but they differ in what they are used for, and how they modify data. Use PUT to modify existing data and POST to add a new record. Remember that using the same POST request repeatedly can have unintended consequences because it is non-idempotent, while using the same PUT request repeatedly will have the same effect.
Becoming confident in request methods is an important step in your programming journey. They might seem a little confusing in the beginning, but knowing when to use a POST, a PUT, or even a PATCH request will make you employ resources more efficiently.
