PATCHes and arrays

You can include arrays in a PATCH request payload. Within the system APIs, PATCHing an array does not add the PATCH members to the members already existing in the array. Instead, the PATCH replaces the existing members with the PATCH members.

For example, in the Jobs API, the JobRoles resource has a roles array. This is an array of users on the job and the role of each user (such as Creator or Underwriter). The following PATCH payload will set the roles array to a single user (user default_data:1) with the role of Auditor. If there were user/role pairs in this array before the PATCH, those pairs will be removed and the only user/role pair will be user default_data:1/Auditor.

{
  "data":
    {
      "attributes": {
        "roles": [
          {
            "group": "systemTables:1",
            "role": {
              "code": "Auditor"
            },
            "user": "default_data:1"
          }
        ]
      }
    }
}

If you want a PATCH to be additive to an array, you must first determine the existing members of the array, and then specify an array in the PATCH with the existing members as well as the ones you wish to add.