REST API Design Best Practices

Chapter 2 · Practice 3 of 4

Use PUT to replace and PATCH to change part of a resource

From HTTP methods and their promises

Why it matters

The difference matters because fields a client omits mean different things:

  • PUT sends the complete new representation. A field left out is removed or reset to its default.
  • PATCH sends only the changes. Fields left out stay as they are.

For PATCH bodies, pick a defined format instead of inventing one:

FormatMedia typeGood for
JSON Merge Patch (RFC 7396)application/merge-patch+jsonSimple object updates; null deletes a field
JSON Patch (RFC 6902)application/json-patch+jsonPrecise operations on arrays and nested paths

Most APIs only need JSON Merge Patch. Whichever you choose, a client that sends {"email": "new@example.com"} with PATCH must not wipe the rest of the profile.

Example

HTTP
PATCH /customers/3
Content-Type: application/merge-patch+json

{ "email": "new@example.com", "phone": null }