> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fynapse.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fynapse.app/_mcp/server.

# 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](https://datatracker.ietf.org/doc/html/rfc7386)), 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:

```json
{
   "id":"b3e63f1f-dbe7-441f-b4dd-12b3410b0ac8",
   "username":"Jane_Doe123",
   "type":"CUSTOM",
   "email":"jd123@example.com",
   "emailVerified":false,
   "enabled":true,
   "displayName":"Jane",
   "roleIds": [
       "3421c6a6-7a5c-4580-8702-8a4c41451207",
       "403195ba-6355-47ed-a483-36e44cf881df"
   ],
   "additionalAttributes":{
      "firstName":[
         "Jane"
      ],
      "lastName":[
         "Doe"
      ]
   },
   "externalGroups": [
      "admin",
      "Group1Example",
      "Group2Example"
    ]  
}
```

#### Example 1: Updating Fields

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

```json
{
  "email": "jane.new@example.com",
  "emailVerified": true
}
```

Resulting resource after applying the patch:

```json
{
   "id":"b3e63f1f-dbe7-441f-b4dd-12b3410b0ac8",
   "username":"Jane_Doe123",
   "type":"CUSTOM",
   "email":"jane.new@example.com",
   "emailVerified":true,
   "enabled":true,
   "displayName":"Jane",
   "roleIds": [
       "3421c6a6-7a5c-4580-8702-8a4c41451207",
       "403195ba-6355-47ed-a483-36e44cf881df"
   ],
   "additionalAttributes":{
      "firstName":[
         "Jane"
      ],
      "lastName":[
         "Doe"
      ]
   },
   "externalGroups": [
      "admin","Group1Example","Group2Example"
    ]
}
```

#### Example 2: Removing Fields

To remove the `firstName` attribute field entirely:

```json
{
  "additionalAttributes": {
      "firstName": null
  }
}
```

Resulting resource:

```json
{
   "id":"b3e63f1f-dbe7-441f-b4dd-12b3410b0ac8",
   "username":"Jane_Doe123",
   "type":"CUSTOM",
   "email":"jane.new@example.com",
   "emailVerified":true,
   "enabled":true,
   "displayName":"Jane",
   "roleIds": [
       "3421c6a6-7a5c-4580-8702-8a4c41451207",
       "403195ba-6355-47ed-a483-36e44cf881df"
   ],
   "additionalAttributes":{
      "lastName":[
         "Doe"
      ]
   },
  "externalGroups": [
    "admin","Group1Example","Group2Example"
    ]
}
```

> **Info**
>
> You can combine updates and deletes in a single PATCH request.

### 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:

```json
"externalGroups": [
  "admin","Group1Example","Group2Example"
]
```

#### Example 1: Replace Entire Array

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

```json
{
  "externalGroups": [
      "admin","Group1Example","Group2Example","Group3Example"
  ]
}
```

Resulting resource:

```json
{
  "externalGroups": [
      "admin","Group1Example","Group2Example","Group3Example"
  ]
}
```

#### Example 2: Clear an Array

To clear an array:

```json
{
  "externalGroups": []
}
```

Resulting resource:

```json
{
  "externalGroups": []
}
```

#### 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:

```json
{
  "externalGroups": [
      "client_admin","Group1Example","Group2Example"
  ]
}
```

Resulting resource:

```json
{
  "externalGroups": [
      "client_admin","Group1Example","Group2Example"
  ]
}
```