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 Claim API, the Claim resource has a witnesses array. This is an array of ClaimContacts who are witnesses to the loss. The following PATCH payload will set the witnesses array to a single witness, the ClaimContact whose id is cc:1306. If there were witnesses in this array before the PATCH, those witnesses will be removed and the only witness will be ClaimContact cc:1306.

{
  "data": {
    "attributes": {
      "witnesses": [
        {
          "contact": {
            "id": "cc:1306"
          }
        }
      ]
    }
  }
}

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.