When building RESTful APIs, updating existing resources is a common operation. Two HTTP methods often come into play for this purpose: PUT and PATCH. While both are used to modify data, they serve distinct functions.
This article will delve into the key differences between PUT and PATCH requests, providing clear examples and guidelines to help you choose the appropriate method for your API.
1. Understanding PUT Requests
Definition of PUT
A PUT request is used to update or create a resource on a server. Think of it as replacing an entire item with a new version. The request includes the entire representation of the resource, and the server should replace the existing resource with the one provided in the request.
Idempotency and Safety of PUT
- Idempotent: A PUT request is idempotent, meaning you can send it multiple times, and it will have the same effect as sending it once. For example, if you update a user’s profile with the same information twice, the result will be the same as updating it once.
- Safe: A PUT request is not considered safe. It modifies data on the server, so it can potentially have side effects.
Use Cases for PUT
- Creating a resource: If a resource doesn’t exist, a PUT request can create it.
- Replacing an entire resource: If a resource already exists, a PUT request replaces it with the new representation sent in the request body.
Examples of PUT Requests
JSON Example
Imagine you have a user resource with the following structure:
{
"id": 1,
"name": "John Doe",
"email": "johndoe@example.com"
}
To update the entire user resource, you would send a PUT request with the updated user data in the request body:
PUT /users/1 HTTP/1.1
Content-Type: application/json
{
"id": 1,
"name": "Jane Doe",
"email": "janedoe@example.com"
}
XML Example
For XML, the structure would be similar:
PUT /users/1 HTTP/1.1 Content-Type: application/xml <user> <id>1</id> <name>Jane Doe</name> <email>janedoe@example.com</email> </user>
The specific format (JSON or XML) depends on the content type specified in the Content-Type header.
2. Understanding PATCH Requests
Definition of PATCH
Unlike PUT, a PATCH request is used to apply partial modifications to a resource. Instead of replacing the entire resource, it specifies changes to specific attributes.
Partial Updates with PATCH
With PATCH, you can modify only the fields you want to change. This is useful when you want to update a small part of a resource without affecting the entire data.
Use Cases for PATCH
- Updating specific fields: Modify only certain attributes of a resource, leaving others unchanged.
- Incremental updates: Apply changes gradually, without replacing the entire resource.
Examples of PATCH Requests
There are different formats for PATCH requests, but we’ll focus on JSON Patch, which is defined by RFC 6902.
JSON Patch Example:
Imagine you want to change the user’s name to “Jane Smith” and increase their age by 1. You would send a PATCH request with the following JSON Patch document:
PATCH /users/1 HTTP/1.1
Content-Type: application/json
[
{"op": "replace", "path": "/name", "value": "Jane Smith"},
{"op": "add", "path": "/age", "value": 1}
]
This example demonstrates how to use JSON Patch operations to modify specific parts of the resource.
Other formats like XML Patch also exist, but JSON Patch is more commonly used.
3. When to Use PUT vs PATCH
Choosing between PUT and PATCH depends on the desired outcome of the request.
General Guidelines
- Use PUT when you want to replace the entire resource with a new version.
- Use PATCH when you want to modify specific parts of a resource without replacing the entire thing.
Considerations
- Idempotency: If the operation needs to be idempotent (producing the same result regardless of the number of times it’s executed), PUT is generally preferred.
- Data Transfer: If you’re sending a large amount of data, PATCH might be more efficient as it only sends the changed parts.
- API Design: Consider the overall design of your API and how these methods align with your resource modeling.
Examples
- Updating a user profile:
- If you want to replace all user information, use PUT.
- If you only want to change the user’s email address, use PATCH.
- Updating a product:
- If you want to replace the entire product with a new version, use PUT.
- If you want to change the product price or description, use PATCH.
Below we will present the cases scenarios in tabular format for better reference
| Scenario | Use PUT | Use PATCH |
|---|---|---|
| Update entire user profile | Yes | No |
| Change user email address | No | Yes |
| Update entire product | Yes | No |
| Change product price or description | No | Yes |
4. Conclusion
Mastering the nuances of PUT and PATCH is a cornerstone of crafting intuitive and efficient RESTful APIs. By understanding their distinct purposes and applying them judiciously, you can significantly enhance the user experience and maintainability of your applications.
While the choice between PUT and PATCH might seem straightforward, the subtleties involved can make a substantial impact on your API’s behavior. It’s my hope that this guide has equipped you with the knowledge to confidently select the appropriate method for your specific use cases.
