PATCH Method

Definition

PATCH is an HTTP method that applies partial modifications to a resource. Unlike PUT (which replaces the entire resource), PATCH updates only the fields specified in the request body. This makes PATCH more efficient for updating large resources when you only need to change a few fields.

PATCH can be idempotent (recommended) or non-idempotent depending on implementation. The request body describes the changes to apply, not the full resource state. Common formats include JSON Patch (RFC 6902), JSON Merge Patch (RFC 7396), or simple field updates.

PATCH is essential for modern APIs where bandwidth efficiency matters, especially for mobile applications or APIs with large resource representations. It enables clients to modify specific attributes without knowing or sending the complete resource structure.

Example

User Profile - Update Email Only:

PATCH /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "email": "[email protected]"
}

Blog Post - Change Status:

PATCH /api/posts/456 HTTP/1.1
Content-Type: application/json

{
  "status": "published",
  "publishedAt": "2026-01-09T10:00:00Z"
}

Product - Update Price and Stock:

PATCH /api/products/SKU-789 HTTP/1.1
Content-Type: application/json

{
  "price": 149.99,
  "stock": 25
}

JSON Patch - Structured Operations:

PATCH /api/users/123 HTTP/1.1
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/email", "value": "[email protected]" },
  { "op": "add", "path": "/phone", "value": "+1-555-0123" },
  { "op": "remove", "path": "/tempField" }
]

Analogy

Editing a Google Doc: PATCH is like making small edits to a document - you change a typo here, add a sentence there, without rewriting the entire document. You don’t create a whole new version (that’s PUT), you just modify the specific parts that need updating.

Adjusting Car Settings: Think of adjusting your car’s side mirrors. You don’t replace the entire car (PUT), you just tweak the mirror position. PATCH is making small adjustments to existing components.

Photo Editing: PATCH is like using the spot healing tool in Photoshop - you fix a specific blemish without redoing the entire image. You’re making targeted corrections, not starting over.

Code Example

// PATCH - Simple field update (JSON Merge Patch)
PATCH /api/users/789 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "department": "Product",
  "role": "manager"
}

// Response - 200 OK
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "8f9e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"

{
  "id": 789,
  "firstName": "Bob",
  "lastName": "Smith",
  "email": "[email protected]",
  "role": "manager",
  "department": "Product",
  "manager": 456,
  "hireDate": "2024-01-15",
  "active": true,
  "updatedAt": "2026-01-09T11:00:00Z"
}

// PATCH - JSON Patch format (RFC 6902)
PATCH /api/users/789 HTTP/1.1
Content-Type: application/json-patch+json

[
  {
    "op": "replace",
    "path": "/email",
    "value": "[email protected]"
  },
  {
    "op": "add",
    "path": "/skills",
    "value": ["javascript", "python", "go"]
  },
  {
    "op": "test",
    "path": "/version",
    "value": 3
  }
]

// Response - 200 OK
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 789,
  "email": "[email protected]",
  "skills": ["javascript", "python", "go"],
  "version": 4
}

// PATCH - Error case (field validation)
PATCH /api/users/789 HTTP/1.1
Content-Type: application/json

{
  "email": "invalid-email"
}

// Response - 400 Bad Request
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "validation_error",
  "message": "Invalid email format",
  "field": "email"
}

// PATCH - Conditional update with ETag
PATCH /api/users/789 HTTP/1.1
If-Match: "8f9e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
Content-Type: application/json

{
  "active": false
}

// Response - 412 Precondition Failed (resource changed)
HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{
  "error": "precondition_failed",
  "message": "Resource has been modified",
  "currentETag": "new-etag-value"
}

Diagram

sequenceDiagram
    participant Client
    participant Server
    participant Database

    Client->>Server: PATCH /api/users/123
    Note over Client,Server: Only changed fields

    Server->>Database: Fetch current resource
    Database-->>Server: Current state

    Server->>Server: Apply partial changes
    Note over Server: Merge/validate fields

    Server->>Database: Update only modified fields
    Database-->>Server: Updated successfully

    Server-->>Client: 200 OK
    Note over Server,Client: Return updated resource

    Client->>Server: PATCH with If-Match header
    Note over Client,Server: Optimistic locking

    Server->>Database: Check ETag/version
    Database-->>Server: ETag mismatch

    Server-->>Client: 412 Precondition Failed
    Note over Server,Client: Prevent lost updates

Security Notes

Best Practices

1. Use for partial updates: PATCH should modify only specified fields
2. Support JSON Merge Patch: Simple field updates (RFC 7396)
3. Consider JSON Patch: For complex operations (RFC 6902)
4. Make it idempotent: Same PATCH should produce same result
5. Return full resource: Response should include complete updated resource
6. Validate partial data: Ensure modified fields maintain consistency
7. Use ETags: Implement optimistic locking with If-Match header
8. Document allowed fields: Clearly specify which fields can be PATCHed
9. Handle null carefully: Define semantics (remove field vs. set to null)
10. Return 200 OK: With updated resource, or 204 No Content if no body

Common Mistakes

Allowing clients to PATCH any field without validation (mass assignment vulnerability). Not implementing idempotency, causing issues on retry. Confusing PATCH with PUT - sending complete resource instead of just changes. Not validating that partial updates maintain data integrity. Forgetting to handle concurrent updates with ETags. Allowing PATCH of read-only or computed fields. Not documenting which fields are patchable. Using PATCH for operations that aren’t really updates (use POST instead). Treating PATCH as non-idempotent when it should be. Not returning the full updated resource in the response.

Standards & RFCs

Related Terms