Meaning
The PATCH method on a resource endpoint applies a partial update to an existing resource identified by its ID. It addresses the inefficiency of sending entire resource representations when only a few fields change. Developers reach for this when a client needs to modify specific attributes without overwriting the whole record.
Primary Function
REST API design
Communicative Purpose
Enables partial modification of a single resource without requiring the full representation, reducing bandwidth and avoiding accidental field overwrites.
Pattern
PATCH /resource/{id} with partial body → server applies diff → returns updated resource or 200/204
Função primária
REST API design
Propósito comunicativo
Enables partial modification of a single resource without requiring the full representation, reducing bandwidth and avoiding accidental field overwrites.
Situações de gatilho
REST API: updating a user profile with only changed fields; CRUD service: toggling a single boolean flag on a record; Microservices: applying incremental state changes to an entity across service boundaries.
Contextos
RESTful web services, HTTP APIs, CRUD backends, microservices, OpenAPI specifications.
Padrão
PATCH /resource/{id} with partial body → server applies diff → returns updated resource or 200/204
Colocados típicos
- JSON Patch (RFC 6902)
- JSON Merge Patch (RFC 7396)
- If-Match header
- ETag
- Content-Type: application/merge-patch+json
- optimistic concurrency control.
Substituições comuns
- PUT /resource/{id} — replaces the entire resource
- risk of dropping unspecified fields
- POST /resource/{id} — non-standard
- semantically ambiguous for updates
- custom action endpoints like /resource/{id}/activate — clearer for single-field state changes.
Erros comuns
1. Using PATCH to send a full replacement body — silently drops fields the client omitted, behaving like PUT. 2. Returning 200 with the full resource when the spec says 204 No Content for empty success — wastes bandwidth. 3. Treating PATCH as idempotent without designing the body to be so — repeating the same PATCH can produce different states. 4. Not validating the Content-Type for JSON Patch vs merge-patch — server may apply patches incorrectly. 5. Ignoring If-Match/ETag — concurrent updates overwrite each other without optimistic locking.
Similar / contraste
PUT /resource/{id} — full replacement, idempotent by definition; POST /resource/{id} — non-idempotent action or create-child; JSON Merge Patch — standardized PATCH body format with null-means-delete semantics.
Interferências
Coming from SOAP: may assume PATCH maps to a generic update operation — REST PATCH is specifically for partial updates and requires careful body design. Coming from RPC frameworks: may treat PATCH as a method call rather than a uniform interface — the verb is fixed, the body shape is the contract.
Família do chunk
- PUT /resource/{id}
- DELETE /resource/{id}
- GET /resource/{id}
- POST /collection
- JSON Merge Patch
- JSON Patch.
Nuance
1. When NOT to use: if the client always knows the full state, PUT is simpler and avoids merge ambiguity. 2. Performance: smaller payloads reduce bandwidth but server-side merge logic can be more expensive than full replacement. 3. Boundary condition: PATCH idempotency depends on the body format — JSON Patch operations like 'add' to an array are not idempotent without a test operation.
Efeito pragmático
Reduces network traffic for sparse updates, prevents accidental data loss from missing fields, and provides a standardized contract for partial modifications across API consumers.
Dica de memória
PATCH is like editing a single line in a shared document — you mark only what changed, and the server merges it into the existing record without rewriting the whole page.
Upgrade path
JSON Patch (RFC 6902) with operational transforms; ETag-based optimistic concurrency; partial response with sparse fieldsets.
Log in to save chunks.