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.
Frequently Asked Questions
What is the main difference between PUT and POST?
POST creates a new subordinate resource and lets the server assign the URI, while PUT creates or updates a resource at a specific URI supplied by the client. The practical rule is: use POST when you don't know the resource location yet, and PUT when you do.
What does idempotent mean, and why does it matter for PUT vs POST?
An idempotent operation produces the same result no matter how many times you repeat it. PUT is idempotent — sending the same PUT request twice leaves the resource unchanged after the first call. POST is not idempotent, so repeating an identical POST request can create duplicate resources, which is a common source of bugs in API integrations.
When should I use PUT instead of POST?
Use PUT when you want to update an existing resource and you already know its URI, for example PUT /users/123 to update user 123. PUT is also appropriate when your client needs to control the resource location rather than having the server generate it. For creating a new resource when the server assigns the ID, POST is the right choice.
What HTTP status codes do PUT and POST return?
POST typically returns 201 Created when a new resource is successfully made, and occasionally 200 OK or 204 No Content. PUT returns 200 OK when an existing resource is updated, or 201 Created when a new resource is created at the specified URI. Neither PUT nor POST responses are cacheable by default.
What is the difference between PUT and PATCH?
PUT replaces the entire resource with the data you send — omitting a field can wipe it. PATCH applies a partial update, only changing the fields included in the request body. If you need to update just one field on a large resource without affecting the rest, PATCH is the safer choice.
Can PUT be used to create a resource, or is that only for POST?
PUT can create a resource if nothing exists at the target URI, and the server will return 201 Created in that case. However, the standard REST pattern is to use POST for creation because it lets the server generate and own the resource identifier. Using PUT for creation only makes sense when the client already knows the exact URI the resource should occupy.
