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.
