application/json-patch+json

API Design

Meaning

The MIME media type identifier for HTTP PATCH request bodies that follow the JSON Patch specification (RFC 6902). It solves the problem of distinguishing partial-update operation lists from full-resource representations during HTTP content negotiation. Reached for when implementing or consuming a REST endpoint that accepts structured, ordered modifications to a resource.

Primary Function

API content negotiation

Communicative Purpose

Ensures clients and servers agree on the JSON Patch document format for partial resource updates over HTTP.

Pattern

set Content-Type header to application/json-patch+json and send JSON Patch operation array in request body

Função primária

API content negotiation

Propósito comunicativo

Ensures clients and servers agree on the JSON Patch document format for partial resource updates over HTTP.

Situações de gatilho

REST API design: defining a PATCH endpoint that accepts a list of operations (add, remove, replace, move, copy, test) HTTP client code: setting the Content-Type header when sending partial updates to a resource API documentation: specifying the media type for partial-update operations in OpenAPI specs

Contextos

REST APIs, HTTP services, microservices, API gateways, OpenAPI specifications, JSON Patch tooling

Padrão

set Content-Type header to application/json-patch+json and send JSON Patch operation array in request body

Colocados típicos

PATCH method
Content-Type header
JSON Patch document (RFC 6902)
If-Match header
ETag
Accept header

Substituições comuns

application/merge-patch+json (RFC 7396) — simpler merge semantics
no array operations or ordering guarantees application/json with custom PATCH body — non-standard
loses tooling and framework support application/json-patch+json with JSON Merge Patch payload — server expects RFC 6902 operations array
not a partial object

Erros comuns

Using application/json instead — server cannot distinguish patch operations from full resource replacement, breaking partial-update semantics Omitting the +json structured suffix — violates RFC 6838/6839 convention and may be rejected by strict content-type validators Sending a JSON Merge Patch document under this media type — server expects an array of op/path/value objects, not a partial JSON object Forgetting to set Accept to the same type — server may respond 406 Not Acceptable even when the patch is valid

Similar / contraste

application/merge-patch+json — simpler shallow-merge semantics, no array manipulation or operation ordering application/json — generic JSON, carries no patch semantics text/x-diff — textual unified diff format, not structured operation objects

Interferências

Coming from SOAP/XML: may expect a single envelope wrapping the patch — JSON Patch is a bare JSON array of operation objects with no wrapper Coming from GraphQL: may try to send mutations as query-shaped documents — JSON Patch uses its own op/path/value vocabulary, not GraphQL selection sets

Família do chunk

application/merge-patch+json
application/json
HTTP PATCH method
JSON Pointer (RFC 6901)
ETag/If-Match

Nuance

When NOT to use: simple full-replacement updates (use PUT with application/json) or when only shallow field merging is needed (use application/merge-patch+json) Performance: the media type string itself has zero overhead; document size scales with operation count, not resource size Boundary condition: the +json suffix per RFC 6839 signals that the payload is JSON, enabling generic JSON parsers to handle it without custom deserializers

Efeito pragmático

Enables standardized, interoperable partial updates across REST APIs with explicit operation semantics, reducing ambiguity between client and server about what is being modified and in what order.

Dica de memória

Like a shipping label on a package — application/json-patch+json tells the server 'open this as a list of surgical instructions, not a full replacement blueprint.'

Upgrade path

JSON Patch RFC 6902 operation semantics (add, remove, replace, move, copy, test) and conditional requests with If-Match/ETag for optimistic concurrency

Frequência: MediumFormulaicidade: Fully fixedPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import requests patch_ops = [ {"op": "replace", "path": "/email", "value": "new@example.com"}, {"op": "add", "path": "/tags/-", "value": "verified"} ] response = requests.patch( "https://api.example.com/users/42", json=patch_ops, headers={"Content-Type": "application/json-patch+json"} )

const express = require('express'); const jsonpatch = require('fast-json-patch'); const app = express(); app.patch( '/users/:id', express.json({ type: 'application/json-patch+json' }), (req, res) => { const user = getUser(req.params.id); const updated = jsonpatch.applyPatch(user, req.body).newDocument; saveUser(updated); res.json(updated); } );

curl -X PATCH https://api.example.com/users/42 \ -H "Content-Type: application/json-patch+json" \ -H "If-Match: \"abc123\"" \ -d '[ {"op": "test", "path": "/version", "value": 3}, {"op": "replace", "path": "/name", "value": "Alice"} ]'