What is PUT?
The REST (REpresentational State Transfer) protocol was designed to standardize HTTP communication between clients and servers. REST is a system of rules and connectors all services must follow and use. If you've ever had to order a special dongle for that one piece of hardware without a USB connector, you understand the problem that REST solves.
REST APIs perform specific methods of data operations across HTTP:
- GET - This operation reads information from a record in the database.
- PUT- This operation changes a record's information in the database.
- POST - This operation creates a new record in the database.
- PATCH - This operation updates an existing resource, but does not require sending the entire body with the request.
- DELETE - This operation removes a record from the database.
In this article we are focusing on the PUT operation. What does PUT do, and how is it different from PATCH and POST? 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."
What does all this mean? 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 API Example
Let's say you change your email address in your Slack 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 or create a new record.
The successful response should be HTTP response code `200 OK` or `201 (created)` (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT).
What is the Difference between PUT, PATCH, and POST?
Maybe you looked at the list of operations above and wondered what the differences are between POST, PUT, and PATCH. We use them 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.
- How is PUT different from POST?
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), but can also perform other actions. See POST for more information on POST requests.
Conclusion
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 a PATCH will make you use resources more efficiently. You might not need to understand the deep mathematical complexities of idempotency, but it's important to know how you are modifying a record with POST, PUT, or PATCH.
Frequently Asked Questions
What is the PUT method in a REST API?
PUT is an HTTP method used to update an existing resource or create a new one at a specific URI. It sends the complete resource data so that the resource at that location is replaced or established.
Is PUT idempotent?
Yes, PUT is idempotent. Sending the same PUT request once or many times in a row produces the same result, so repeated identical requests do not cause additional changes.
What is the difference between PUT and POST?
POST creates records and is not idempotent, so repeated identical requests can have cumulative effects such as duplicates. PUT places the complete resource at a specified URI and is idempotent, so repeating it does not change the outcome.
What is the difference between PUT and PATCH?
PATCH applies a partial update and does not require the entire resource body. PUT typically requires the complete resource data because it replaces the resource at the URI.
What status codes does a successful PUT request return?
A successful PUT request returns 200 OK when it updates an existing resource, or 201 Created when it creates a new resource.
What does a PUT request look like in practice?
A PUT request targets a specific resource URI and sends the full data for that resource. For example, updating a user could use PUT https://www.abstractapi.com/users/{{userID}} with the complete resource body.
