What's the Difference Between PUT and POST?

Last Updated Aug 17, 2021
Emma Jagger

Engineer, maker, Google alumna, CMU grad

PUT and POST are both REST API requests. REST APIs perform specific methods of data operations across HTTP, called HTTP requests. These are a little like the Create, Read, Update, and Delete CRUD operations, but sent via an Application Programming Interface, or API.

  • GET request- This operation reads information from a record in the database.  
  • PUT request- This operation changes a record's information in the database.  
  • POST request - This operation creates a new record in the database.  
  • PATCH request- This operation updates an existing resource, but does not require sending the entire body with the request.  
  • DELETE request- This operation removes a record from the database.  

PUT and POST both perform modifications on existing data, but they do so differently because of idempotence. PUT modifies a record's information and creates a new record if one is not available, and POST creates a new subordinate resource at the URI (Universal Resource Identifier).

A programmer should know the differences between the two, because using HTTP PUT and HTTP POST correctly means a more efficient and predictable software solution. PUT will update an existing child resource, while POST creates a new resource. Neither PUT or POST HTTP responses are cacheable.

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.

Related articles

No items found.
Start using one of Abstract's 10+ API's for free today
Get started