PingOne Advanced Identity Cloud

Patch

To patch a resource, send an HTTP PATCH request with an array of operation objects in the payload. Each operation object uses some combination of these fields:

operation

The type of operation.

field

The target field.

value

The value to apply.

from

The source field.

The service applies the PATCH operations in order.

PATCH /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-Match: _rev
{ JSON array of patch operations }

PATCH operations work differently depending on the field types:

Single-value

An object, string, boolean, or number.

List semantics array

The elements are ordered, and duplicates are allowed.

Set semantics array

The elements are not ordered, and duplicates are not allowed.

Whether an endpoint supports a specific operation depends on the implementation.

Add operation

The add operation ensures the target field contains the value provided, creating parent fields as necessary.

If the target field is single-valued, the value replaces the value of the target.

If the value is an array, the outcome depends on the type:

List semantics arrays

If you add an array of values, the operation appends the array to the existing list of values.

If you add a single value, specify an ordinal element in the target array, or use the {-} special index to add the value to the end of the list.

Set semantics arrays

The operation merges the value(s) in the patch with the existing set of values. Any duplicates in the array are removed.

As an example, start with the following list semantic array resource:

{
  "fruits": ["orange", "apple"]
}

The following add operation appends pineapple at the end of the array:

{
  "operation": "add",
  "field": "/fruits/-",
  "value": "pineapple"
}

The resulting resource is:

{
  "fruits": ["orange", "apple", "pineapple"]
}

Copy operation

The copy operation replaces the value(s) of the target field with the value(s) from the source field.

The following example replaces the value of another_mail with the value of mail:

[{
  "operation": "copy",
  "from": "mail",
  "field": "another_mail"
}]

If the source field value and the target field value are arrays, the result depends on whether the array has list semantics or set semantics. Learn more in Add operation.

Increment operation

The increment operation changes the value or values of the target field by the amount you specify. The value must be a positive or negative number. The target must be a single-valued number.

The following example adds 1000 to /user/payment:

[{
  "operation": "increment",
  "field": "/user/payment",
  "value": "1000"
}]

Move operation

The move operation removes existing values from the source and adds them to the target field. The operation creates the target field if it does not exist.

The following example moves surname values to lastName:

[{
  "operation": "move",
  "from": "surname",
  "field": "lastName"
}]

To apply a move to an array, the source and target must have compatible semantics. Learn more in Add operation.

Remove operation

The remove operation deletes values in the target field.

When no value is specified, the operation removes the field:

[{
  "operation": "remove",
  "field": "phoneNumber"
}]

For arrays, the result depends on the semantics:

List semantic arrays

Delete the specified element in the array.

The following example removes the first phone number (zero-based array index):

[{
  "operation": "remove",
  "field": "/phoneNumber/0"
}]
Set semantic arrays

Delete the specified values from the array.

The following example removes the specified phone number:

[{
  "operation": "remove",
  "field": "/phoneNumber",
  "value": "+1 408 555 9999"
}]

Replace operation

The replace operation removes existing values in the target, replacing them with the provided value(s).

The following example replaces existing telephoneNumber values with +1 408 555 9999:

[{
  "operation": "replace",
  "field": "/telephoneNumber",
  "value": "+1 408 555 9999"
}]

For list semantic arrays, you can target items by their indexes. As an example, start with the following resource:

{
  "fruits": ["apple", "orange", "kiwi", "lime"]
}

Apply the following operation:

[{
  "operation": "replace",
  "field": "/fruits/1",
  "value": "pineapple"
}]

The result is:

{
  "fruits": ["apple", "pineapple", "kiwi", "lime"]
}

Transform operation

The transform operation changes the field value based on a script or a data transformation command.

The following example applies the something.js script to the /objects value:

[{
  "operation": "transform",
  "field": "/objects",
  "value": {
    "script": {
      "type": "text/javascript",
      "file": "something.js"
    }
  }
}]

Limitations

Some HTTP client libraries do not support the HTTP PATCH operation.

Make sure the library you use supports HTTP PATCH before using this REST operation. For example, the Java method HttpURLConnection.setRequestMethod("PATCH") throws ProtocolException.

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.