Patch Request

A PATCH request edits selected attributes of a resource. The modifications are specified in a patch document. A PATCH document contains a list of patch operations, each of which updates one attribute. Here is an patch document with four operations.

[ { "op": "replace", "path": "/name", "value": "arnon ron" },
  { "op": "remove", "path": "/addresses/12345" },
  { "op": "add", "path": "/addresses/1" },
  { "op": "replace", "path": "/addresses/1/address", "value": "arnon.ron@xelion.nl" }]

The first line in the patch document above sets the value of the attribute name to "arnon ron". The second line removes the object with OID 12345 from the relation addresses. The third line adds a new object to the relation addresses. The fourth line sets the address attribute of the object added by the previous line.

Dealing with relations

The attributes of an object are set by replace operations. Relations with other objects, for example the orgnisations that employ a person, are managed by add and remove operations.

An add operation must append a virtual object ID (OID) to the member path. This OID can be any number and is selected by the client program. The virtual OID groups the operations on the relation object together (note that a new object requires at least one replace value operation, or else the object will be empty).
The system replaces the virtual OID with a real OID when the patch document is processed. Hence next time the object is retrieved a new OID is returned.

Consider for example the type Person which has an Employment relation with Organisation. Let’s say we want to add a new employment relation. First we have to write an add operation that links the organisation with the person. Supposing the organisation has the OID 24689753 we write:

  { "op": "add", "path": "/employments/1", "value": "24689753" }

The path element "1" in "/employments/1" is a placeholder for the relation object OID. It’s could be any positive number you choose.

Let’s set the job-title of the person.

  { "op": "add", "path": "/employments/1", "value": "24689753" },
  { "op": "replace", "path": "/employments/1/jobTitle" "value": "programmer" }

Now we want to add a telephone number to this employment relation. By doing that the system will create a new phone number object. Considering that we don’t know the OID of the new object, we’ll write an add operation without specifying the value:

  { "op": "add", "path": "/employments/1", "value": "24689753" },
  { "op": "replace", "path": "/employments/1/jobTitle", "value": "programmer" },
  { "op": "add", "path": "/employments/1/1" },
  { "op": "replace", "path": "/employments/1/telecomAddresses/1/address", "value": "06-56473829" }

The path "/employments/1/telecomAdresses/1/address" stands for: 'the address of the telecom address 1 in the employment relation 1. Both relations are new, and will be created by the patch operation.

Removing an employment is done by specifying the OID of the employment (thus not the organisation’s OID!).

  { "op": "remove", "path": "/employments/112358" }