Backend Study Lab

API Design

PUT vs PATCH in REST APIs

Compare PUT and PATCH in REST APIs, including replacement vs partial updates, idempotency, validation, status codes, and backend implementation choices.

By CloveCode Studio Jun 30, 2026 Updated Jun 30, 2026 4 min read

PUT and PATCH both update resources, but they communicate different contracts to clients.

Quick answer

Use PUT when the client sends a complete replacement representation for a resource. Use PATCH when the client sends a partial change.

PUT is expected to be idempotent: sending the same request multiple times should leave the resource in the same final state. PATCH can be idempotent, but only if the patch format and backend behavior make it so.

What PUT means

PUT means “replace the resource at this URI with this representation.”

PUT /users/123
Content-Type: application/json
{
  "name": "Ava Chen",
  "email": "ava@example.com",
  "timezone": "America/New_York"
}

The client is saying: this is the new representation of /users/123. If a field is omitted, the API must define whether that omission is invalid, resets the field, or is ignored. For a clean PUT contract, omission usually means the representation is incomplete.

Some APIs also allow PUT to create a resource at a known URI:

PUT /settings/accounts/acct_123/preferences

That can be reasonable when the client knows the resource identity ahead of time.

What PATCH means

PATCH means “apply this partial change to the resource.”

PATCH /users/123
Content-Type: application/json
{
  "timezone": "Europe/London"
}

The client is not sending the whole user. It is only changing one field.

This is useful when resources are large, clients edit one form section at a time, or different clients own different fields. It also avoids accidental data loss when a client does not know every field on the resource.

Patch document formats

Many APIs use a simple partial JSON object:

{
  "displayName": "Ava",
  "marketingOptIn": false
}

That is easy to understand, but it needs clear rules for missing fields and null values.

Other APIs use formal patch formats. JSON Patch describes operations with paths:

[
  { "op": "replace", "path": "/timezone", "value": "Europe/London" }
]

JSON Merge Patch uses a partial object where null often means remove the field:

{
  "middleName": null
}

If your API uses JSON Pointer paths, the JSON Pointer Resolver can help debug exact path behavior in examples.

Idempotency differences

PUT should be idempotent. If the client sends the same complete representation five times, the final state should be the same as sending it once.

PATCH depends on the operation.

This patch is usually idempotent:

{
  "timezone": "Europe/London"
}

This operation may not be idempotent:

[
  { "op": "add", "path": "/loginCount", "value": 1 }
]

If retries are possible, define whether your patch operations are duplicate-safe. Read Idempotency in APIs Explained before designing update endpoints that clients may retry.

Validation and status codes

For successful updates, common responses include:

ScenarioPossible response
Updated and returning the resource200 OK
Updated and no body needed204 No Content
Resource created by PUT201 Created
Invalid request body400 Bad Request
Field validation failed422 Unprocessable Entity
Version or state conflict409 Conflict
Resource not found404 Not Found

Use status codes consistently across update endpoints. Read REST API Status Codes Explained and REST API Error Handling Best Practices before finalizing error behavior.

Backend implementation checklist

For PUT, decide whether the endpoint requires every writable field. Validate that clients cannot accidentally wipe server-owned fields such as id, createdAt, billing state, permissions, or audit metadata.

For PATCH, define allowed fields and patch operations. Do not let clients update arbitrary database columns just because they appear in JSON.

For both methods:

  • Validate the authenticated user can update the resource.
  • Keep server-owned fields server-owned.
  • Return a stable error shape.
  • Consider optimistic locking when lost updates are possible.
  • Document whether null removes a field or sets it to a null value.
  • Keep examples in docs aligned with the real schema.

Use the JSON Schema Generator to draft request and response examples, and use JSON to TypeScript to inspect client-side type shapes.

Common mistakes

The first mistake is treating PATCH as “smaller PUT” without defining partial update semantics. Clients need to know what missing fields and null values mean.

The second mistake is using PUT for partial updates while silently preserving omitted fields. That surprises clients who expect replacement semantics.

The third mistake is allowing updates to every field in the payload. API request models should be explicit, especially for permissions, billing, ownership, and security-sensitive fields.

The fourth mistake is ignoring concurrency. If two clients update the same resource at the same time, the second update may overwrite the first unless the API uses version checks or another conflict strategy.

Read REST vs RPC for API style choices and API Versioning Explained before changing update semantics in a public API. For retry-safe write behavior, read Idempotency in APIs Explained. Use the HTTP Status Code Lookup while designing 200, 201, 204, 409, and 422 responses. For the full sequence, browse the API Design Learning Path and the Topics map.

Keep reading