Patch Specification

API Documentation / Patch Specification

For partial updates of existing resources the hetras API requires the payload to be based on IETF JSON Patch RFC 6902.

Supported operations

Not all attributes of a resource are eligible to being changed or removed. A good example is the reservation status which is the result of some actions performed on a reservation and therefore cannot be set explicitly. To make the life of the developers easier the API will validate the JSON patch payload and respond with the http status code 422 if you want to perform an operation that is not allowed. This should only happen during implementation and give you a way to explore the capabilities of the API interactively.

Handling of Arrays

JSON Patch is very powerful, but it has minor shortcomings when it comes to updating arrays. The standard only supports accessing items using the index, but most of the time it makes more sense to access them using keys.

Simple arrays

Instead of using the index for the add and remove operations, we use the value of the array member in the path expression to identify the member. This approach is used for arrays of primitive types, like strings or integers. In the following example, we remove a specific value from an array of strings:

Original Resource

{
“labels”: [
MOBILE”,
DONOTDISTURB
]
}

Request

[
{
“op”: “remove”,
“path”: “/labels/MOBILE
}
]

Resulting Resource

{
“labels”: [
DONOTDISTURB
]
}

Complex arrays

Instead of using the index for the add and remove operations, we use the value of a specific key property in the path expression to identify the member. This approach is used for arrays of objects, like customers in a reservation or phone numbers in a profile. The value of the key property itself cannot be changed. In the following example, we change a phone number in an array of phones:

Original Resource

{
“phones” : [{
“key”: “HomeVoice”,
“location”: “Home”,
“type” : “Voice”,
“number” : “+6643441”,
“primary” : true
}
]
}

Request

[
{
“op”: “replace”,
“path”: “/phones/HomeVoice/number”,
“value”: “+7059657”
}
]

Resulting Resource

{
“phones” : [{
“key”: “HomeVoice”,
“location”: “Home”,
“type” : “Voice”,
“number” : “+7059657”,
“primary” : true
}
]
}