1. Customization & development

Four reasons to stop using PUT for updates

When updating existing resources, developers often ask whether to use PUT or PATCH. This guide explains why PATCH is the recommended choice for updates.

Key recommendation: Use PATCH

PATCH offers several advantages over PUT for resource updates:

1. Network efficiency

  • PUT requires sending complete objects
  • PATCH only sends changed fields
  • Reduces network payload size
  • Improves performance

2. Simplified operations

  • PUT often requires initial GET request
  • PATCH needs only object ID
  • Reduces API calls
  • Streamlines updates

3. Default value preservation

  • PUT can override inherited defaults
  • Some properties inherit parent values
  • GET returns current defaults
  • PUT may break inheritance chain
  • PATCH preserves inheritance

4. Concurrency handling

Example scenario:

  • User A modifies quantity multiplier
  • User B modifies description
  • Both users GET product data
  • User A sends PUT with changes
  • User B's PUT reverts A's changes

Solution with PATCH:

  • User A patches quantity only
  • User B patches description only
  • Changes remain independent
  • No unintended overwrites

Appropriate PUT usage

Resource creation with ID

When to use:

  • Creating new resources
  • You provide the ID
  • ID goes in URI only
  • REST: "Put this object here"

Note: Use POST for auto-generated IDs.

Complete object replacement

When to use:

  • Same ID (location)
  • Different real-world object
  • Rare use case
  • Full replacement needed

Relationship objects

When to use:

  • Objects without unique IDs
  • Identity from other values
  • Assignment operations
  • Limited verb availability

PUT advantages

Idempotency

Benefits:

  • Multiple calls safe
  • Same end state
  • No duplicate checking
  • Predictable results

Note: POST creates new resources on each call.

Assignment operations

Benefits:

  • No existence check needed
  • Creates or overwrites
  • Handles duplicates
  • Simplifies relationships

HTTP verb usage guide

POST usage

Use for:

  • Platform-generated IDs
  • New resource creation
  • ID in response body
  • URI in Location header

PUT usage

Use for:

  • User-provided IDs
  • Complete replacements
  • Relationship objects
  • ID in request URI

PATCH usage

Use for:

  • Existing resource updates
  • Partial modifications
  • Resource "moves"
  • Old ID in URI, new in body
If you have suggestions for improving this article, let us know!