Concept
Patch Requests
PATCH requests are a bit different than other HTTP requests. These follow the guidelines of the JSONPatch (IETF: RFC 6902) standard. A generic example taken from the definition can be seen below.
PATCH /api/v1/departments/[ID] HTTP/1.1
Content-type: application/json-patch+json
Authorization: Bearer [Your token]
[
{ "op": "test", "path": "/a/b/c", "value": "foo" },
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
]
While application/json-patch+json is the preferred content-type, we also accept
application/json and will handle it the same.
Working with Arrays
JSON Patch provides special syntax for working with arrays. You can reference array elements by index,
or use - to append to the end of an array.
Array Operations
[
{ "op": "add", "path": "/items/0", "value": "first item" },
{ "op": "add", "path": "/items/-", "value": "append to end" },
{ "op": "replace", "path": "/items/1", "value": "replace second item" },
{ "op": "remove", "path": "/items/0" }
]Permissions Examples
When working with permissions, you can add, replace, or remove permission objects. Here are some practical examples:
Adding a New Permission
[
{
"op": "add",
"path": "/permissions/-",
"value": {
"userGroups": ["095ec644-dc96-4977-beda-77f0075f6ba7"],
"departments": ["ae71b3c5-e34e-4f42-b92e-60d527ee1e89"],
"requireAllUserGroups": false
}
}
]Replacing All Permissions
[
{
"op": "replace",
"path": "/permissions",
"value": [
{
"userGroups": ["095ec644-dc96-4977-beda-77f0075f6ba7"],
"departments": ["ae71b3c5-e34e-4f42-b92e-60d527ee1e89"],
"requireAllUserGroups": false
}
]
}
]Modifying Specific Permission Properties
[
{
"op": "replace",
"path": "/permissions/0/requireAllUserGroups",
"value": true
},
{
"op": "add",
"path": "/permissions/0/userGroups/-",
"value": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]Removing Permissions
[
{
"op": "remove",
"path": "/permissions/0"
}
]Complex Nested Operations
You can perform multiple operations in a single request. Operations are applied in order, so the path references reflect the document state after previous operations.
[
{
"op": "replace",
"path": "/categoryId",
"value": "12345678-1234-1234-1234-123456789012"
},
{
"op": "add",
"path": "/permissions/-",
"value": {
"userGroups": ["095ec644-dc96-4977-beda-77f0075f6ba7"],
"departments": ["ae71b3c5-e34e-4f42-b92e-60d527ee1e89"],
"requireAllUserGroups": false
}
},
{
"op": "replace",
"path": "/notifications/sendNotification",
"value": true
}
]Important Notes
-
Array Indexing: Arrays are zero-indexed.
/items/0refers to the first element. -
Append Operation: Use
-to append to the end of an array:/items/- - Path Escaping: If property names contain special characters, they must be escaped according to JSON Pointer specification.
- Operation Order: Operations are applied sequentially. Later operations see the results of earlier ones.
- Validation: The entire document is validated after all operations are applied.
Error Handling
If any operation in the patch fails, the entire request fails and no changes are applied. Common errors include:
- Invalid path (e.g., referencing a non-existent array index)
- Type mismatches (e.g., trying to add a string to a number field)
- Validation failures after applying operations