PATCH, POST, PUT & DELETE

This article will explain when to use each of the verbs and any nuances.

POST

The POST verb allows you to create a new object. All required fields must be in the payload. Let's create a country with the following details:

{
    "name": "Germany",
    "sortOrder": "5",
    "countryAddressFormatId": 10,
    "dataTypePostalCodeId": 88,
    "countryCode": "DE",
    "isVisible": true
  }

We note the response:

{
  "trackingId": "e163a2ea-978c-4c27-9a24-180338c6e8a5",
  "type": "create",
  "results": {
    "totalCount": 1,
    "items": [
      {
        "identity": 255,
        "action": "created",
        "dtoTypeKey": "country",
        "instance": {
          "identity": 255,
          "name": "Germany",
          "sortOrder": 5,
          "countryAddressFormatId": 10,
          "countryAddressFormatName": "Address Level 1",
          "dataTypePostalCodeId": 88,
          "dataTypePostalCodeName": "No Validation",
          "countryCode": "DE",
          "isVisible": true
        }
      }
    ]
  }
}

PUT

The PUT verb allows you to update properties of an object. You must use the update request header and supply only the properties that need updating with the Update Request header. For more details see Update Requests.

PATCH

The PATCH verb allows you to update an object. Just like a put, you only need to supply the fields that will be updated in the payload. However, a patch allows you to update many objects at once. Many objects in the platform are hierarchical in nature - consider an account package that has services and those services in turn have usage identifiers. To update the parent object we would use PUT. But, if you want to update one or more of the children/grandchildren use PATCH. Patch offers a couple of benefits over PUT in that:

Patch operations are transactional - if an update fails anywhere in the hierarchy the entire transaction is rolled back so you are not caught with a partial update
Object relationships can be implied by the data structure so you are free from the burden of determining the foreign key - If you are updating the usage identifier on an account service you do not have to worry about the account service or an linking tables since you are sending the structure.

Rule of Thumb: Use PUT for parent updates, Use PATCH for children

DELETE

You can delete an object as long as it is not referenced by another entity.