# API Patch Strategies

> Choose JSON Patch (RFC 6902) vs Merge Patch (RFC 7386) for REST PATCH, including media types, null semantics, Accept-Patch, and If-Match concurrency. Use when designing partial updates or reviewing PATCH handlers.

- Skill: `deangrant/api-patch-strategies` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/api-patch-strategies`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/api-patch-strategies/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/api-patch-strategies

---


# PATCH Strategies: JSON Patch vs Merge Patch

Use this skill when implementing **partial updates**. Arbitrary partial JSON is
ambiguous — use RFC media types; wrong `Content-Type` → **415**.

Advertise supported formats with `Accept-Patch` (often on OPTIONS).

---

## 1. JSON Patch (RFC 6902)

`Content-Type: application/json-patch+json` — ordered ops; JSON Pointer paths;
all-or-nothing.

Ops: `add`, `remove`, `replace`, `move`, `copy`, `test`.

Best for: array element edits, assertions (`test`), auditability, explicit null.

---

## 2. Merge Patch (RFC 7386)

`Content-Type: application/merge-patch+json` — partial object; **null deletes**;
omit = unchanged; nested objects merge; **arrays replace wholesale**.

Best for: object-centric local-copy edits from clients.

---

## 3. Concurrency and security

- Require `If-Match` (strong ETag) → **412** on mismatch; missing may be **428**.
- Whitelist patchable paths; cap body size / op count; authz per path.
- Never treat PATCH like PUT (omitted fields nulled) unless Merge Patch null rules apply.

---

## 4. Quick checklist

- [ ] One format (or both with distinct media types + 415).
- [ ] `Accept-Patch` documented.
- [ ] Null/omit semantics documented.
- [ ] `If-Match` on contested resources.
- [ ] Path allowlist + size/op caps.
- [ ] Errors: 400 / 409 / 412 / 415 / 422.

See [reference.md](reference.md) and [examples.md](examples.md).