Patch
Note
Examples in this documentation depend on features activated in the ds-evaluation setup profile.
For details, see "Learn About the Evaluation Setup Profile".
Patching is updating part of the resource rather than replacing the resource. For example, you could change Babs Jensen's email address with an HTTP PATCH request:
$curl \ --user kvaughan:bribery \ --cacert ca-cert.pem \ --request PATCH \ --header "Content-Type: application/json" \ --data '[ { "operation": "replace", "field": "/contactInformation/emailAddress", "value": "babs@example.com" } ]' \ --silent \ https://localhost:8443/api/users/bjensen?_prettyPrint=true{ "_id" : "bjensen", "_rev" : "<revision>", "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0", "_meta" : { "lastModified" : "<datestamp>" }, "userName" : "babs@example.com", "displayName" : [ "Barbara Jensen", "Babs Jensen" ], "name" : { "givenName" : "Barbara", "familyName" : "Jensen" }, "description" : "Original description", "contactInformation" : { "telephoneNumber" : "+1 408 555 1862", "emailAddress" : "babs@example.com" }, "uidNumber" : 1076, "gidNumber" : 1000, "homeDirectory" : "/home/bjensen", "manager" : { "_id" : "trigden", "_rev" : "<revision>" }, "groups" : [ { "_id" : "Carpoolers" } ] }
Notice in the example that the data sent specifies the type of patch operation, the field to change, and a value that depends on the field you change and on the operation. A single-valued field takes an object, boolean, string, or number depending on its type, whereas a multi-valued field takes an array of values. Getting the type wrong results in an error. Also notice that the patch data is itself an array. This makes it possible to patch more than one part of the resource by using a set of patch operations in the same request.
DS software supports these patch operations:
addThe add operation ensures that the target field contains the value provided, creating parent fields as necessary.
If the target field is single-valued and a value already exists, then that value is replaced with the value you provide. Note that you do not get an error when adding a value to a single-valued field that already has a value. A single-valued field is one whose value is not an array (an object, string, boolean, or number).
If the target field is multi-valued, then the array of values you provide is merged with the set of values already in the resource. New values are added, and duplicate values are ignored. A multi-valued field takes an array value.
removeThe remove operation ensures that the target field does not contain the value provided. If you do not provide a value, the entire field is removed if it already exists.
If the target field is single-valued and a value is provided, then the provided value must match the existing value to remove, otherwise the field is left unchanged.
If the target field is multi-valued, then values in the array you provide are removed from the existing set of values.
replaceThe replace operation removes existing values on the target field, and replaces them with the values you provide. It is equivalent to performing a remove on the field, then an add with the values you provide.
incrementThe increment operation increments or decrements the value or values in the target field by the amount you specify, which is positive to increment and negative to decrement. The target field must take a number or a set of numbers. The value you provide must be a single number.
One key nuance in how a patch works with DS software concerns multi-valued fields. Although JSON resources represent multi-valued fields as arrays, DS software treats those values as sets. In other words, values in the field are unique, and the ordering of an array of values is not meaningful in the context of patch operations. If you reference array values by index, DS software returns an error. DS software does, however, allow use of a hyphen to add an element to a set. Include the hyphen as the last element of the field JSON pointer path as in the "/members/-" field of this example patch: [{ "operation" : "add", "field" : "/members/-", "value" : { "_id" : "bjensen" } }].
Perform patch operations as if arrays values were sets. The following example includes Barbara Jensen in a group by adding her to the set of members:
$curl \ --user kvaughan:bribery \ --request PATCH \ --cacert ca-cert.pem \ --header "Content-Type: application/json" \ --data '[{ "operation": "add", "field": "/members", "value": [{"_id": "bjensen"}] }]' \ --silent \ https://localhost:8443/api/groups/Directory%20Administrators?_prettyPrint=true{ "_id" : "Directory Administrators", "_rev" : "<revision>", "_schema" : "frapi:opendj:rest2ldap:group:1.0", "_meta" : { "lastModified" : "<datestamp>" }, "displayName" : "Directory Administrators", "members" : [ { "_id" : "kvaughan" }, { "_id" : "rdaugherty" }, { "_id" : "hmiller" }, { "_id" : "bjensen" } ] }
The following example removes Barbara Jensen from the group:
$curl \ --user kvaughan:bribery \ --request PATCH \ --cacert ca-cert.pem \ --header "Content-Type: application/json" \ --data '[{ "operation": "remove", "field": "/members", "value": [{"_id": "bjensen"}] }]' \ --silent \ https://localhost:8443/api/groups/Directory%20Administrators?_prettyPrint=true{ "_id" : "Directory Administrators", "_rev" : "<revision>", "_schema" : "frapi:opendj:rest2ldap:group:1.0", "_meta" : { "lastModified" : "<datestamp>" }, "displayName" : "Directory Administrators", "members" : [ { "_id" : "kvaughan" }, { "_id" : "rdaugherty" }, { "_id" : "hmiller" } ] }
To change the value of more than one attribute in a patch operation, include multiple operations in the body of the JSON patch, as shown in the following example:
$curl \ --user kvaughan:bribery \ --request PATCH \ --cacert ca-cert.pem \ --header "Content-Type: application/json" \ --data '[ { "operation": "replace", "field": "/contactInformation/telephoneNumber", "value": "+1 408 555 9999" }, { "operation": "add", "field": "/contactInformation/emailAddress", "value": "barbara.jensen@example.com" } ]' \ --silent \ https://localhost:8443/api/users/bjensen?_prettyPrint=true{ "_id" : "bjensen", "_rev" : "<revision>", "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0", "_meta" : { "lastModified" : "<datestamp>" }, "userName" : "barbara.jensen@example.com", "displayName" : [ "Barbara Jensen", "Babs Jensen" ], "name" : { "givenName" : "Barbara", "familyName" : "Jensen" }, "description" : "Original description", "contactInformation" : { "telephoneNumber" : "+1 408 555 9999", "emailAddress" : "barbara.jensen@example.com" }, "uidNumber" : 1076, "gidNumber" : 1000, "homeDirectory" : "/home/bjensen", "manager" : { "_id" : "trigden", "_rev" : "<revision>" }, "groups" : [ { "_id" : "Carpoolers" } ] }
Notice that for a multi-valued attribute, the value field takes an array, whereas the value field takes a single value for a single-valued field. For single-valued fields, an add operation has the same effect as a replace operation.
You can use resource revision numbers in If-Match: revision headers to patch the resource only if the resource matches a particular version, as shown in the following example:
$export REVISION=$(cut -d \" -f 8 <(curl --silent \ --user kvaughan:bribery \ --cacert ca-cert.pem \ https://localhost:8443/api/users/bjensen?_fields=_rev))$curl \ --user kvaughan:bribery \ --request PATCH \ --cacert ca-cert.pem \ --header "If-Match: $REVISION" \ --header "Content-Type: application/json" \ --data '[ { "operation": "add", "field": "/contactInformation/emailAddress", "value": "babs@example.com" } ]' \ --silent \ https://localhost:8443/api/users/bjensen?_prettyPrint=true{ "_id" : "bjensen", "_rev" : "<new-revision>", "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0", "_meta" : { "lastModified" : "<datestamp>" }, "userName" : "babs@example.com", "displayName" : [ "Barbara Jensen", "Babs Jensen" ], "name" : { "givenName" : "Barbara", "familyName" : "Jensen" }, "description" : "Original description", "contactInformation" : { "telephoneNumber" : "+1 408 555 9999", "emailAddress" : "babs@example.com" }, "uidNumber" : 1076, "gidNumber" : 1000, "homeDirectory" : "/home/bjensen", "groups" : [ { "_id" : "Carpoolers" } ], "manager" : { "_id" : "trigden", "_rev" : "<revision>" } }
The resource revision changes when the patch is successful.