Log in
What is the HTTP PATCH method?
The HTTP PATCH method applies partial modifications to a resource identified by a specific URI. PATCH addresses a common API design need: updating specific fields without replacing entire resources.
When you only need to update part of a resource, such as changing a user’s email address or adjusting a product price, the HTTP PATCH method is the best fit. Introduced in RFC 5789, PATCH applies partial updates to an existing resource, making it more efficient than PUT for targeted updates.
This guide explains what the PATCH method is, how it differs from PUT and POST, and how to implement PATCH requests effectively with Postman.
Example: Updating a user’s role
PATCH /api/users/12345 HTTP/1.1
Content-Type: application/json
{
"role": "Senior Developer"
}The server updates only the role field and leaves all other properties unchanged:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "12345",
"name": "Patia Ostman",
"email": "p.ostman@example.com",
"role": "Senior Developer"
}PATCH vs PUT vs POST
Understanding when to use PATCH, PUT, and POST is fundamental to RESTful API design.
| Method | Purpose | Data sent | Idempotent? | Typical use case |
|---|---|---|---|---|
| PATCH | Partial update | Only changed fields | Sometimes* | Update specific fields on a resource Example: PATCH /users/123 |
| PUT | Full replacement | Complete resource | Yes | Replace entire resource Example: PUT /users/123 |
| POST | Create or action | New resource data | No | Create new resources or trigger actions Example: POST /users |
*PATCH is not inherently idempotent, but many APIs design PATCH requests to be idempotent when possible.
How the same update behaves differently
PATCH: send only what changes
PATCH /api/users/12345 HTTP/1.1
Content-Type: application/json
{
"email": "newemail@example.com"
}Result: Only the email field is updated.
PUT: send everything
PUT /api/users/12345 HTTP/1.1
Content-Type: application/json
{
"id": "12345",
"name": "Patia Ostman",
"email": "newemail@example.com",
"role": "Developer"
}Result: The entire resource is replaced. If you omit any fields, they might be removed or reset to default values.
When not to use PATCH
PATCH is powerful, but it isn’t always the right choice.
Avoid PATCH when:
-
You intend to replace the entire resource (use PUT instead).
-
Updates are inherently non-idempotent (consider POST for action-based changes).
-
Your API contract requires full validation of all fields on every update.
-
The resource does not yet exist (return 404 and use POST to create).
PATCH request formats
APIs typically support PATCH using one of two formats: merge-based updates or operation-based updates.
JSON merge patch
A merge patch sends a JSON object containing only the fields to update:
PATCH /api/users/12345
Content-Type: application/merge-patch+json
{
"email": "updated@example.com",
"role": "Manager"
}This approach is simple and intuitive, but it can be ambiguous for nested objects and null values.
JSON Patch
JSON Patch (RFC 6902) provides precise control using an array of operations:
PATCH /api/users/12345 Content-Type: application/json-patch+json [ { “op”: “replace”, “path”: “/email”, “value”: “new@example.com” }, { “op”: “add”,
PATCH /api/users/12345
Content-Type: application/json-patch+json
[
{ "op": "replace", "path": "/email", "value": "new@example.com" },
{ "op": "add", "path": "/phone", "value": "+1-555-0123" },
{ "op": "remove", "path": "/temporary_field" }
]Available operations:
-
add→ Add a new field or array element -
remove→ Delete a field -
replace→ Update an existing field -
move→ Move a value to a different location -
copy→ Copy a value to a new location -
test→ Verify a value before applying operations
Common PATCH response codes
Success responses:
-
200 OK → Update succeeded, returns the updated resource
-
204 No Content → Update succeeded with no response body
-
202 Accepted → Update accepted for asynchronous processing
Error responses:
-
400 Bad Request → Invalid patch format or data
-
401 Unauthorized → Authentication required
-
403 Forbidden → Insufficient permissions
-
404 Not Found → Resource doesn’t exist
-
409 Conflict → Update conflicts with the current resource state
-
422 Unprocessable Entity → Valid JSON, but semantically incorrect
Understanding PATCH idempotency
Idempotency means that applying the same request multiple times produces the same result as applying it once. This property is crucial for safely handling network retries.
PATCH is not inherently idempotent, but many APIs design PATCH requests to behave idempotently for reliability and safe retries.
Idempotent PATCH example:
PATCH /api/users/12345
{
"email": "consistent@example.com"
}Sending this request multiple times results in the same final state.
Non-idempotent PATCH example:
PATCH /api/products/789
{
"inventory_adjustment": -5 // Subtract 5 from inventory
}Each request subtracts 5 inventory, resulting in a different final state.
Best practices for idempotency
Use absolute values instead of relative changes:
Non-idempotent:
{ "views": "+1" }
Idempotent:
{ "views": 1501 }For operations that require relative updates, use dedicated POST endpoints for actions rather than PATCH for modifications.
Real-world PATCH use cases
PATCH is ideal for targeted updates across many domains.
User profile updates
PATCH /api/users/profile
{ "bio": "API enthusiast and developer advocate" }E-commerce inventory
PATCH /api/products/789
{ "price": 29.99, "inventory": 47 }Application settings
PATCH /api/settings
{ "theme": "dark", "notifications": true }Task management
PATCH /api/tasks/456
{ "status": "completed", "completed_at": "2024-11-24T14:30:00Z" }Content publishing
PATCH /api/articles/789
{ "status": "published", "featured": true }Testing PATCH requests in Postman
Postman makes it easy to test PATCH endpoints and verify partial update behavior.
Creating a PATCH request
-
Click New → HTTP Request.
-
Select PATCH from the method dropdown.
-
Enter the endpoint URL:
https://api.example.com/users/12345 -
Add headers:
-
Content-Type: application/json -
Authorization: Bearer your_token
-
-
Add the request body:
{
"email": "newemail@example.com"
}-
Click Send to see the response.
Testing partial updates
Create multiple requests to verify that only the specified fields change.
Test 1: Update email only
{ "email": "test1@example.com" }Test 2: Update role only
{ "role": "Manager" }Send a GET request after each PATCH to confirm other fields remain unchanged.
Adding test scripts
Verify PATCH responses automatically:
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
pm.test("Email was updated", function () {
const jsonData = pm.response.json();
pm.expect(jsonData.email).to.eql("newemail@example.com");
});
pm.test("Other fields unchanged", function () {
const jsonData = pm.response.json();
pm.expect(jsonData.name).to.exist;
});Best practices for PATCH implementation
Follow these guidelines to build reliable PATCH endpoints.
Design PATCH to be idempotent where possible
Prefer absolute field values over incremental updates.
Document patchable fields
Clearly specify which fields can be modified and which cannot.
PATCH /api/users/{id}
Patchable fields:
- email (string, valid email format)
- role (string: "user", "admin", "manager")
- preferences (object)
Protected fields (cannot be patched):
- id, created_at, usernameValidate before applying changes
Validate all fields first and apply updates only if all validations pass.
// Validate all fields first
if (patch.email && !isValidEmail(patch.email)) {
return 400;
}
if (patch.role && !validRoles.includes(patch.role)) {
return 400;
}
// Only apply if all validations pass
applyPatch(resource, patch);Handle null explicitly
Differentiate between omitted fields (leave unchanged) and explicit null values (clear the field).
Return the updated resource
After a successful PATCH, return the complete updated resource so clients can confirm changes.
PATCH security considerations
Because PATCH modifies existing data, strong security controls are essential.
Require authentication and authorization
Always verify the caller’s identity and ensure their permissions are valid. Make sure that users can only modify resources they own or have permission to edit.
Restrict access to sensitive fields
Never allow PATCH to modify system-managed or security-critical fields, such as id, created_at, password_hash, or permission flags.
Validate all input
Treat PATCH data like any user input. Validate types, formats, and ranges to prevent injection attacks and data corruption.
Enforce HTTPS
PATCH requests often contain sensitive data. Always use HTTPS to encrypt data in transit.
Apply rate limiting
Prevent abuse by limiting PATCH requests per user or IP address.
Common mistakes to avoid
-
Treating PATCH like PUT. Don’t require all fields in a PATCH request. Send only what needs to change.
-
Creating resources with PATCH instead of POST. Return 404 Not Found when trying to PATCH non-existent resources. Use POST to create resources.
-
Allowing updates to immutable fields. Protect system-managed fields from modification through clear validation rules.
-
Ignoring dependencies between related fields. Some fields depend on others. Validate these relationships before applying changes.
-
Skipping transport security. Even with proper authentication, always use HTTPS to encrypt PATCH requests and protect sensitive data.
FAQs
| Question | Answer |
|---|---|
| When should you use PATCH? | When you need to update specific fields on an existing resource without replacing it entirely. |
| When should you use PUT? | When replacing an entire resource. |
| Is PATCH idempotent? | Not inherently idempotent, but well-designed PATCH implementations should strive for idempotency. |
| Can PATCH create resources? | No. PATCH modifies existing resources. Use POST to create new resources. |
| How are null values handled? | It depends on the implementation. Typically, explicit nulls clear a field; omitted fields remain unchanged. |
| Which Content-Type should I use? | Use application/json for simple merges,application/json-patch+json for RFC 6902 operations. |
Final thoughts
The HTTP PATCH method is primarily used to express what changes should be made to a resource without resending its entire state. When PATCH requests are clearly scoped, validated upfront, and designed to behave predictably, they reduce accidental data loss and make APIs easier to evolve over time. Used this way, PATCH becomes a powerful tool for building APIs that scale without breaking clients.
The post HTTP PATCH Method: Partial Updates for RESTful APIs appeared first on Postman Blog.
