PATCH Updates

We follow the JSON Patch format convention to partially update some Workiva Platform API resources. For more information, refer to the endpoint-specific documentation and examples.

Examples

Add Operation

The add operation is used to add a new value to a resource. If the path specifies an array index, a new value is inserted at that location. If the path specifies an object key that does not already exist, a new key-value pair is added to the object.

Example using a numerical index:

[
    {
        "op": "add",
        "path": "/tags/1",
        "value": "Finance"
    }
]

For this resource:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": ["Tech"]
}

The result will be:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": ["Tech", "Finance"]
}

Example appending to the end of a list:

[
    {
        "op": "add",
        "path": "/tags/-",
        "value": "Finance"
    }
]

This operation appends the value “Finance” to the end of the tags list. Specifying ‘-’ as the index in the path indicates that the value should be added to the end of a list.

For this resource:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": []
}

The result will be:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": ["Finance"]
}

Replace Operation

The replace operation is used to replace an existing value in a resource. The specified path must already exist, and the value at that path is replaced by the new value provided.

Example:

[
    {
        "op": "replace",
        "path": "/name",
        "value": "Updated Name"
    }
]

For this resource:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description"
}

The result will be:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Updated Name",
    "description": "Example Description"
}

Remove Operation

The remove operation is used to remove a value from a resource. If the path specifies an array index, the value at that index is removed. If the path specifies an object key, the key-value pair is removed from the object.

Example:

[
    {
        "op": "remove",
        "path": "/tags/0"
    }
]

For this resource:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": ["Tech", "Finance"]
}

The result will be:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": ["Finance"]
}

Test Operation

The test operation is used to test if a value at a specified path is equal to another specified value. This can be used to verify the state of a resource before applying further operations.

Example:

[
    {
        "op": "test",
        "path": "/name",
        "value": "Example Name"
    }
]

For this resource:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description"
}

The test will pass because the current name matches the name specified in the test. If the names did not match, a 409 Conflict would be returned.

Multiple Operations

If needed, a single call can provide multiple operations. This allows for complex updates to a resource in a single request.

Example:

[
    {
        "op": "test",
        "path": "/tags/0",
        "value": "Tech"
    },
    {
        "op": "test",
        "path": "/tags",
        "value": ["Tech", "Finance"]
    },
    {
        "op": "replace",
        "path": "/name",
        "value": "Updated Name"
    },
    {
        "op": "add",
        "path": "/tags/-",
        "value": "Marketing"
    },
    {
        "op": "remove",
        "path": "/tags/0"
    }
]

For this resource:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Example Name",
    "description": "Example Description",
    "tags": ["Tech", "Finance"]
}

The result of applying the multiple operations will be:

{
    "id": "242a56d3cc0742c8abad0820bd318b23",
    "name": "Updated Name",
    "description": "Example Description",
    "tags": ["Finance", "Marketing"]
}

Explanation:

1. The first test operation verifies that the first tag is “Tech”. If this test fails, none of the subsequent operations are performed.

2. The second test operation verifies that the entire tags array is [“Tech”, “Finance”]. If this test fails, none of the subsequent operations are performed.

3. The replace operation updates the name to “Updated Name”.

4. The add operation adds a new tag “Marketing” to the tags array.

5. The remove operation removes the first tag “Tech” from the tags array.

Because all operations are successful, the resulting resource has the updated name, the first tag removed, and a new tag added.

Handling Conflicts

To handle conflicts when using a PATCH endpoint, use the test operation to verify the data before applying further operations, as described above.