Using HTTP PATCH

The PATCH action is an alternative to the traditional GET, POST, PUT, or DELETE verb. When available, it lets individuals submit only the fields that should be changed without having to load up a full item beforehand.

Structure of PATCH Calls

When a web API endpoint is PATCH-based, calls to it should contain a JSON Patch document in the request body. This document is an array of different patch operations, which can be represented as TeamDynamix.Api.JsonPatchOperation instances.

This generally follows the guidelines outlined by the JSON Patch standard, with the following exceptions:

1. When accessing unordered subcollections on items (such as a ticket's custom attributes), items are referenced by their ID and not their position in the collection. This also means that the special /- index cannot be used.
2. The property name matching is case-insensitive.
3. Because the items in question have a pre-defined set of properties, the add and copy operations cannot be used to add new properties. Similarly, the remove and move operations cannot be used to remove properties - only clear them out.
4. The test operation is currently not supported.

Handling Custom Attributes

In the interests of simplicity, custom attributes, as mentioned above, are handled somewhat differently when they are on an item that can be patched. To access a specific attribute, the ID of the attribute, instead of its index of its position in the custom attributes collection, is used. In addition, only the value of the attribute needs to be submitted instead of a full CustomAttribute instance. In the case of choice-based attributes, the value will be a string containing the ID (or, in the case of multiple selections, a comma-separated list of IDs) of the selected choice(s).

Example PATCH Request

For a given item with "Title" and "Account" properties, as well as a custom attributes collection with the name "Attributes", the following sample request body will set the title, account, and a custom attribute with ID 1234. It will also clear the custom attribute with ID 5678.