/
RESTful comparison of PATCH (update) and PUT (replace)

RESTful comparison of PATCH (update) and PUT (replace)

Owned by Arpit Singh
Last updated: Jan 15, 2025
6 min read

Page Title

Decisions

Page Title

Decisions

No decisions found

Objective

The document provides a comprehensive deep dive into the PATCH and PUT operations as per the RESTful principles. We compare the two operations and to find out the major differences in their implementations and best practices to resolve the issues found in the “Update node leaves” and “Replace node leaves” APIs in CPS

Comparison of PATCH and PUT based on RESTful principles

Aspect

PATCH (Update)

PUT (Replace)

Aspect

PATCH (Update)

PUT (Replace)

Purpose

PATCH is used to update specific fields of a data, while leaving the other fields unchanged.

PUT is used to replace the entire resource with new data. Any fields that are not included in the replacement payload are either set to a default value or removed.

Payload Format

  • For PATCH the payload requires only the fields being updated.

  • This reduces the size of payload.

  • PUT requires the payload to contain all the fields, even the ones that are unchanged.

  • This increases the size and complexity of payload.

Impact on server state

PATCH only modifies the specified fields sent as part of the payload.

The remaining fields are left untouched

PUT overwrites the entire data.

Fields not provided in the payload are removed.

HTTP response codes

  • 200 OK: resource was successfully updated

  • 409 Conflict: when the request cannot be applied given the state of the resource. For example, if the client attempted to apply a structural modification and the structures assumed to exist did not exist

  • 200 OK: resource was successfully replaced

  • 201 Created: if new data was created as part of replace operation

Idempotency

PATCH is not always Idempotent as sending the same request multiple times may result in same resource state for the updated fields. But in some scenarios, this may not be true.

PUT is Idempotent, it means that, regardless of how many times an action is performed, the results will be the same as the first time. 

Idempotency Example

If a PUT request is modifying a counter, then sending the same request multiple times will reset the counter with each request. Whereas the same is not true for PATCH

If we issue a POST request several times, it will create multiple resources with the same content. On the contrary, if we issue the same PUT request multiple times, it will not have any effects on the specified resource, beyond the first time. This is because the POST request will create a new resource every time whereas the PUT request will keep overwriting the same resource.

Atomicity

PATCH is usually non-atomic because it updates specific fields individually while others are unaffected.

PUT is an atomic operation because either whole resource is updated or no change occurs.

Overhead

Lower overhead because only fields being updated are sent as part of request.

Higher overhead because all the fields are sent as part of request, even the ones not changed.

Handling Creation of a new resource using PATCH

In RESTful APIs, the PUT method is commonly used to create a new resource if it doesn't exist.

According to RFC 5789, which defines the PATCH method, if the target resource does not exist, using PATCH to create new resources is generally not recommended. The primary purpose of PATCH is to apply partial modifications to existing resources, and its behavior when the resource doesn't exist can be unpredictable or inconsistent across different implementations.

Handling scenario where a new resource is provided as part of PATCH

Conflicting state: Can be specified with a 409 (Conflict) status code when the request cannot be applied given the state of the resource. For example, if the client attempted to apply a structural modification and the structures assumed to exist did not exist (with XML, a patch might specify changing element ’foo’ to element ’bar’ but element ’foo’ might not exist).

Based on the above abstract from RFC 5789, when a PATCH request is received, and the server determines that the resource does not exist, the server may return a 409 Conflict to indicate that the request cannot be fulfilled due to a conflict with the current state of the server. This response code is appropriate when the semantics of the patch document do not permit resource creation via a PATCH request.

Examples of PATCH operation

Description

Original Server State

PATCH payload

Server state after PATCH operation

Response Code

Description

Original Server State

PATCH payload

Server state after PATCH operation

Response Code

Updating a leaf node

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": 1,
"name": "Kids"
}
}

{
"categories": {
"code": "1",
"name": "Kids",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

200 Ok

Updating a leaf and a leaf list

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

 

IDEAL Payload

{
"title": "Matilda",
"editions":[2024],
"price": 25
}

OR

{
"title": "Matilda",
"editions":[1988, 2000, 2024],
"price": 25
}

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 25,
"editions": [1988,2000,2024]

OR

"editions":[1988, 2000, 1988, 2000, 2024],
}
]
}
}

200 OK

Updating a leaf while also adding a new list item with key "title": "The Gruffalo" in the list node books

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"books": [
{
"title": "Matilda",
"price": 25
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia"],
"editions": [1999],
"price": 15
}
]
}
}

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

409 Conflict

Updating leaves in multiple nodes

{
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia"],
"editions": [1999],
"price": 15
}
]
}

{
"books": [
{
"title": "Matilda",
"price": 20,
"editions": [2025]
},
{
"title": "The Gruffalo",
"price": 150
}
]
}

{
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 20,
"editions": [1988,2000,2025]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia"],
"editions": [1999],
"price": 150
}
]
}

200 OK

Examples of PUT operation

Description

Original Server State

PATCH payload

Server state after PATCH operation

Response
Code

Description

Original Server State

PATCH payload

Server state after PATCH operation

Response
Code

Replacing a leaf node

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Kids",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Kids",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

200 OK

Replacing a leaf node and entire list

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Kids"
}
}

{
"categories": {
"code": "1",
"name": "Kids"
]
}
}

200 OK

Using PUT to create a new list

{
"categories": {
"code": "1",
"name": "Children"
}
}

{
"categories": {
"code": "1",
"name": "Kids",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Kids",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

201 Created

Using PUT to add a new list item

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia"],
"editions": [1999],
"price": 15
}
]
}
}

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia"],
"editions": [1999],
"price": 15
}
]
}
}

201 Created

Replacing an entire list with a new list item

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia"],
"editions": [1999],
"price": 15
}
]
}
}

{
"categories": {
"code": "1",
"books": [
{
"title": "New Book",
      "lang": "English",
"price": 0,
"editions": [2025]
}
]
}
}

{
"categories": {
"code": "1",
"books": [
{
"title": "New Book",
      "lang": "English",
"price": 0,
"editions": [2025]
}
]
}
}

200 OK

Replacing entire leaf list using PUT

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [1988,2000]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [2025]
}
]
}
}

{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
      "lang": "English",
"price": 200,
"editions": [2025]
}
]
}
}

200 OK

References