REST API design

Enables partial, idempotent modification of a specific nested resource without affecting the parent or sibling entries.

REST API design: updating a single field of a nested resource such as a user's address or an order's line item API versioning: maintaining backward-compatible partial updates on sub-collections across releases Microservices: exposing fine-grained mutation endpoints for child aggregates owned by an aggregate root

RESTful HTTP APIs, OpenAPI/Swagger specifications, microservices, web frameworks (Express, Spring, Django REST), API gateways

PATCH /{parent_resource}/{parent_id}/{subresource}/{subresource_id}

PATCH /{...}/{id}/{...}

parent_resource: string (plural noun naming the parent collection) parent_id: string or integer (unique identifier of the parent resource) subresource: string (plural noun naming the child collection) subresource_id: string or integer (unique identifier of the child resource being patched)

• Content-Type: application/merge-patch+json or application/json-patch+json headers
• If-Match/ETag for optimistic concurrency
• OpenAPI path-item definitions
• JSON Merge Patch (RFC 7396)
• JSON Patch (RFC 6902)

• PUT /resource/{id}/subresource/{sub_id}: replaces the entire sub-resource instead of merging — heavier payload and loses untouched fields POST /resource/{id}/subresource/{sub_id}: non-idempotent and breaks REST conventions for state mutation PATCH /resource/{id}: patches the parent instead of the child — wrong scope when only the sub-resource changes

Returning 200 with the full updated sub-resource when the spec only requires 200/204 — wastes bandwidth on large nested objects Omitting If-Match/ETag validation — allows lost-update races when two clients patch the same sub-resource concurrently Using PATCH to replace the entire sub-resource body — semantically a PUT; confuses clients and breaks partial-update assumptions Forgetting to validate that {id} and {subresource_id} both exist before applying the patch — surfaces as 500 instead of 404 Sending PATCH with Content-Type: application/json when merge semantics are assumed — server may reject or apply the body as a full replacement

PUT /resource/{id}/subresource/{sub_id}: full replacement of the sub-resource, not partial PATCH /resource/{id}: partial update of the parent resource itself, one level up POST /resource/{id}/subresource: creates a new child, does not modify an existing one

Coming from RPC/SOAP: may treat PATCH as a generic remote procedure — REST PATCH is specifically a partial-state mutation with defined merge semantics, not an arbitrary verb Coming from GraphQL: may expect a single mutation endpoint — REST requires distinct URL paths per sub-resource scope

• REST resource patterns
• HTTP PATCH semantics
• JSON Merge Patch
• JSON Patch
• nested resource addressing

When NOT to use: if the sub-resource does not yet exist (use POST to create), if the entire sub-resource is being replaced (use PUT), or if the change set is large enough that PUT is simpler Performance: PATCH payloads are typically smaller than PUT, reducing bandwidth; however, servers must compute the merge, which can be costlier than a simple overwrite on large documents Boundary: RFC 5789 defines PATCH semantics but leaves merge behavior to content types — application/merge-patch+json (RFC 7396) and application/json-patch+json (RFC 6902) have different conflict-resolution rules

Reduces network payload for small changes, avoids race conditions on full replacements via ETag concurrency, and keeps API contracts stable as sub-resource schemas evolve.

PATCH on a sub-resource path is like editing one field in a nested form — you don't resubmit the whole form, just the changed field, and the server knows exactly which nested box you mean.

JSON Patch (RFC 6902) with operational transformations for fine-grained, auditable sub-resource mutations