PATCH Operation Format

Overview

This article provides information on the procedure for performing partial updates.

The PATCH operation allows partial updates to a resource, making it a more efficient alternative to PUT when only certain fields need to be modified. We adopt the JSON Merge Patch format (as defined in RFC 7396), which provides a straightforward and human-readable way to represent changes. Unlike the JSON Patch format, which relies on an array of operations (add, remove, replace), JSON Merge Patch requires simply submitting the modified parts of the resource in standard JSON.

Key Characteristics of JSON Merge Patch:

1. Simpler Syntax: Changes are expressed as a regular JSON object with updated key-value pairs.
2. Idempotent: Reapplying the same PATCH request results in the same state.
3. Field Removal: Fields can be removed by setting their value to null.

Basic Examples

Imagine a resource representing a user profile, structured as follows:

1
{
2
   "id":"b3e63f1f-dbe7-441f-b4dd-12b3410b0ac8",
3
   "username":"Jane_Doe123",
4
   "type":"CUSTOM",
5
   "email":"jd123@example.com",
6
   "emailVerified":false,
7
   "enabled":true,
8
   "displayName":"Jane",
9
   "roleIds": [
10
       "3421c6a6-7a5c-4580-8702-8a4c41451207",
11
       "403195ba-6355-47ed-a483-36e44cf881df"
12
   ],
13
   "additionalAttributes":{
14
      "firstName":[
15
         "Jane"
16
      ],
17
      "lastName":[
18
         "Doe"
19
      ]
20
   },
21
   "externalGroups": [
22
      "admin",
23
      "Group1Example",
24
      "Group2Example"
25
    ]  
26
}

Example 1: Updating Fields

To change the email and emailVerified fields, the PATCH request body would be:

1
{
2
  "email": "jane.new@example.com",
3
  "emailVerified": true
4
}

Resulting resource after applying the patch:

1
{
2
   "id":"b3e63f1f-dbe7-441f-b4dd-12b3410b0ac8",
3
   "username":"Jane_Doe123",
4
   "type":"CUSTOM",
5
   "email":"jane.new@example.com",
6
   "emailVerified":true,
7
   "enabled":true,
8
   "displayName":"Jane",
9
   "roleIds": [
10
       "3421c6a6-7a5c-4580-8702-8a4c41451207",
11
       "403195ba-6355-47ed-a483-36e44cf881df"
12
   ],
13
   "additionalAttributes":{
14
      "firstName":[
15
         "Jane"
16
      ],
17
      "lastName":[
18
         "Doe"
19
      ]
20
   },
21
   "externalGroups": [
22
      "admin","Group1Example","Group2Example"
23
    ]
24
}

Example 2: Removing Fields

To remove the firstName attribute field entirely:

1
{
2
  "additionalAttributes": {
3
      "firstName": null
4
  }
5
}

Resulting resource:

1
{
2
   "id":"b3e63f1f-dbe7-441f-b4dd-12b3410b0ac8",
3
   "username":"Jane_Doe123",
4
   "type":"CUSTOM",
5
   "email":"jane.new@example.com",
6
   "emailVerified":true,
7
   "enabled":true,
8
   "displayName":"Jane",
9
   "roleIds": [
10
       "3421c6a6-7a5c-4580-8702-8a4c41451207",
11
       "403195ba-6355-47ed-a483-36e44cf881df"
12
   ],
13
   "additionalAttributes":{
14
      "lastName":[
15
         "Doe"
16
      ]
17
   },
18
  "externalGroups": [
19
    "admin","Group1Example","Group2Example"
20
    ]
21
}

Array Update Examples

JSON Merge Patch handles arrays differently than objects. With JSON Merge Patch, an array is treated as a whole, meaning it will replace the entire array rather than modifying individual elements.

Key Considerations for Arrays

1. Array Overwrites: JSON Merge Patch replaces an entire array when a key maps to a new array.
2. No In-Place Operations: You cannot directly update, add, or remove individual elements in an array. Instead, you provide the entire updated array.
3. Empty Arrays: To clear an array, provide an empty array ([]) as the value.

Let’s consider the externalGroups array:

1
"externalGroups": [
2
  "admin","Group1Example","Group2Example"
3
]

Example 1: Replace Entire Array

To update the externalGroups array to ["admin","Group1Example","Group2Example","Group3Example"]:

1
{
2
  "externalGroups": [
3
      "admin","Group1Example","Group2Example","Group3Example"
4
  ]
5
}

Resulting resource:

1
{
2
  "externalGroups": [
3
      "admin","Group1Example","Group2Example","Group3Example"
4
  ]
5
}

Example 2: Clear an Array

To clear an array:

1
{
2
  "externalGroups": []
3
}

Resulting resource:

1
{
2
  "externalGroups": []
3
}

Example 3: Partial Updates are Not Supported for Arrays

If you attempt to modify a single element in the externalGroups array, such as changing "admin" to "client_admin", you must provide the entire updated array. For example:

1
{
2
  "externalGroups": [
3
      "client_admin","Group1Example","Group2Example"
4
  ]
5
}

Resulting resource:

1
{
2
  "externalGroups": [
3
      "client_admin","Group1Example","Group2Example"
4
  ]
5
}