What is a PUT request?
A PUT request is a set of instructions sent to the API, to update a record’s information. Opposite to PATCH, PUT alters the entire data of a resource. That means, that whatever figures in the body of the request will be the resource after the request has been successfully implemented.
PUT can also be used to create new resources. The content of the request is essentially the same as when modifying existing ones. But, since the soon-to-be resource will not have already a URL, you’ll have to define one when writing the request.
Idempotency: PUT vs. POST
One of the definitory traits of PUT requests is its idempotency. Technically speaking, idempotency is a mathematical concept. But, when it comes to PUT requests, it means that, regardless of how many times an action is performed, the results will be the same as the first time.
Let’s take POST requests, for example. If you issue a POST request several times, for whatever reason, you will create multiple resources with the same content. On the contrary, if you issue several times a single PUT request, it will not have any effects on the specified resource, beyond the first time.
In other words, a PUT request affects a single resource. If a PUT request is repeated, it will not alter that resource, since it already displays the request’s data. This ensures that the REST API will be reliable and perform consistently, avoiding duplicates, processing errors, and unwanted results.
H3: Script of a PUT
Let’s have an example of how a PUT request to modify or create a resource would look like:
fetch('https://api.example.com/usuarios/123', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-access-token'
},
body: JSON.stringify({
name: "John Smith",
email: "john.smith@example.com"
age: “30”
})
})
In this case, you seek to change or create a user’s profile (user 123), assuming that all the profile fields are his name, email, and age. The “fetch” function will allow you to send the request to the API server, using JavaScript.
What is a PATCH request?
A PATCH request is a set of instructions to alter some pieces of data, that an API stores in a server. That is, it only updates a few sections of existing resources, or “child resources”.
Think about it changing an entire outfit (PUT request) vs. changing only a shirt (PATCH request). While the first one alters your entire appearance, the second one modifies only a specific part of it.
Its content is roughly the same as in a PUT request, but the “body” section only displays the data that are to be modified. Therefore, the rest of the script’s content should remain unchanged once the request is executed.
By sending fewer data and not updating an entire resource, PATCH proves to be a more efficient method than PUT. At least, when specific changes are required.
Unlike PUT, PATCH is not idempotent, which means that sending multiple times a single PATCH request might yield different results. That is because PATCH alters a resource based on its current state… And, after the first time a PATCH request is sent, the resource at issue will be already modified.
This, as well as the fact that not all servers accept PATCH, often causes PUT to be more commonly used than PATCH
Script of a PATCH
A PATCH request for changing only the age of a user (the same user as the PUT example) would look like this:
fetch('https://api.example.com/usuarios/123', {
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-access-token'
},
body: JSON.stringify({
age: “31”
})
})
As you can see, the field “age” displays the content that has to be updated as it should be after it is modified. The method name has also been changed, from PUT to PATCH.
PUTCH vs. PATCH
In brief, the main distinctions between PATCH and PUT are the following ones:
- PUT updates an entire resource. PATCH, only the sections of it which are specified.
- PATCH is more efficient than PUT.
- PUT is idempotent, while PATCH is not.
- PATCH is not accepted by every server. PUT, normally, yes.
When to use PATCH or PUT?
Now that you know the differences between PUT and PATCH, it is time to delve into when each one of those methods should be used, to ensure your API works properly.
PUT requests are to be issued in the following situations:
- When fully replacing a resource’s content. The PUT request will have to provide the data for every field of the resource. When not, the field may be set in default mode or be eliminated.
- Scenarios that requiere idempotency. That is when one has to make sure a request will always have the same result, notwithstanding how many times it is sent.
- When creating a new resource. PUT can be preferred over POST as a means of creating new resources when the client knows the desired identifier of the resource beforehand. In other words, its location. It is also a better option than POST when idempotency is needed.
By contrast, PUT requests are recommended for:
- Partial modifications. PATCH updates only certain fields of a specific resource, listed in the request’s script. This implies more efficient management of an API’s content, preventing unintended modifications and enhancing fluency in data exchange.
- Frequent updates & scenarios that require efficiency. Since only the necessary content is sent and altered, fluency in updates, frequents or not, is assured.
- Complex resources, with big data. Using PATCH helps to avoid accidentally deleting information since only the fields listed in the script will be modified.
Can PATCH and PUT be used interchangeably?
Though it is not always recommended, PUT can be used as a PATCH request in very specific situations.
The script example provided above is one of those specific situations. Why? Because it has a simple structure, with little data. Therefore, the speed of the request will not be substantially affected, and filling every field of the resource in the script will not pose any inconvenience.
In brief…
PATCH and PUT are key factors when updating an API’s resources. While PUT allows for a more “total” altering of its content, PATCH provides punctual modifications. Both of them “protect” the resource against unwanted changes, though each one has its own methods to do it.
Choosing between PATCH or PUT depends mostly on the amount of data you plan to update and the complexity of the resources involved. Knowing when to use each one, helps you make sure that an API’s resources are used more efficiently and, of course, it improves its user’s experience.
