--- title: Patch description: To patch a resource, send an HTTP PATCH request with the following parameters: component: pingidm version: 8.1 page_id: pingidm::crest/crest-patch canonical_url: https://docs.pingidentity.com/pingidm/8.1/crest/crest-patch.html keywords: ["Rest", "REST API", "JSON"] section_ids: crest-patch-add: "Patch Operation: Add" crest-patch-copy: "Patch Operation: Copy" crest-patch-increment: "Patch Operation: Increment" crest-patch-move: "Patch Operation: Move" crest-patch-remove: "Patch Operation: Remove" crest-patch-replace: "Patch Operation: Replace" crest-patch-transform: "Patch Operation: Transform" crest-patch-limitations: Patch Operation Limitations --- # Patch To patch a resource, send an HTTP PATCH request with the following parameters: * `operation` * `field` * `value` * `from` (optional with copy and move operations) You can include these parameters in the payload for a PATCH request, or in a JSON PATCH file. If successful, you'll refer to a JSON response similar to: ```http 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 apply to three types of targets: * **single-valued**, such as an object, string, boolean, or number. * **list semantics array**, where the elements are ordered, and duplicates are allowed. * **set semantics array**, where the elements are not ordered, and duplicates are not allowed. Ping PATCH supports several different `operations`. The following sections show each of these operations, along with options for the `field` and `value`: ## Patch Operation: Add The `add` operation ensures that the target field contains the value provided, creating parent fields as necessary. If the target field is single-valued, then the value you include in the PATCH replaces the value of the target. Examples of a single-valued field include: object, string, boolean, or number. An `add` operation has different results on two standard types of arrays: * **List semantic arrays**: you can run any of these `add` operations on that type of array: * If you `add` an array of values, the PATCH operation appends it 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 that value to the end of the list. * **Set semantic arrays**: The value included in the patch is merged with the existing set of values. As an example, start with the following list semantic array resource: ```javascript { "fruits" : [ "orange", "apple" ] } ``` The following add operation includes the pineapple to the end of the list of fruits, as indicated by the `-` at the end of the `fruits` array. ```javascript { "operation" : "add", "field" : "/fruits/-", "value" : "pineapple" } ``` The following is the resulting resource: ```javascript { "fruits" : [ "orange", "apple", "pineapple" ] } ``` Note that you can add only one array element one at a time, as per the corresponding [JSON Patch specification](https://www.rfc-editor.org/rfc/rfc6902.html#appendix-A.16). If you add an array of elements, for example: ```javascript { "operation" : "add", "field" : "/fruits/-", "value" : ["pineapple", "mango"] } ``` The resulting resource would have the following invalid JSON structure: ```javascript { "fruits" : [ "orange", "apple", ["pineapple", "mango"]] } ``` ## Patch Operation: Copy The copy operation takes one or more existing values from the source field. It then adds those same values on the target field. Once the values are known, it is equivalent to performing an `add` operation on the target field. The following `copy` operation takes the value from a field named `mail`, and then runs a `replace` operation on the target field, `another_mail`. ```javascript [ { "operation":"copy", "from":"mail", "field":"another_mail" } ] ``` If the source field value and the target field value are configured as arrays, the result depends on whether the array has list semantics or set semantics, as described in [Patch Operation: Add](#crest-patch-add). ## Patch Operation: Increment The `increment` operation changes the value or values of the target field by the amount you specify. The value that you include must be one number, and may be positive or negative. The value of the target field must accept numbers. The following `increment` operation adds `1000` to the target value of `/user/payment`. ```javascript [ { "operation" : "increment", "field" : "/user/payment", "value" : 1000 } ] ``` Since the `value` of the `increment` is a single number, arrays don't apply. ## Patch Operation: Move The move operation removes existing values on the source field. It then adds those same values on the target field. It is equivalent to performing a `remove` operation on the source, followed by an `add` operation with the same values, on the target. The following `move` operation is equivalent to a `remove` operation on the source field, `surname`, followed by a `replace` operation on the target field value, `lastName`. If the target field does not exist, it is created. ```javascript [ { "operation":"move", "from":"surname", "field":"lastName" } ] ``` To apply a `move` operation on an array, you need a compatible single-value, list semantic array, or set semantic array on both the source and the target. For details, refer to the criteria described in [Patch Operation: Add](#crest-patch-add). ## Patch Operation: Remove The `remove` operation ensures that the target field no longer contains the value provided. If the remove operation does not include a value, the operation removes the field. The following `remove` deletes the value of the `phoneNumber`, along with the field. ```javascript [ { "operation" : "remove", "field" : "phoneNumber" } ] ``` If the object has more than one `phoneNumber`, those values are stored as an array. A `remove` operation has different results on two standard types of arrays: * **List semantic arrays**: A `remove` operation deletes the specified element in the array. For example, the following operation removes the first phone number, based on its array index (zero-based): ```javascript [ { "operation" : "remove", "field" : "/phoneNumber/0" } ] ``` * **Set semantic arrays**: The list of values included in a patch are removed from the existing array. ## Patch Operation: Replace The `replace` operation removes any existing value(s) of the targeted field, and replaces them with the provided value(s). It is essentially equivalent to a `remove`, followed by a `add` operation. If the arrays are used, the criteria is based on [Patch Operation: Add](#crest-patch-add). However, indexed updates are not allowed, even when the target is an array. The following `replace` operation removes the existing `telephoneNumber` value for the user, and then adds the new value of `+1 408 555 9999`. ```javascript [ { "operation" : "replace", "field" : "/telephoneNumber", "value" : "+1 408 555 9999" } ] ``` A PATCH replace operation on a list semantic array works in the same fashion as a PATCH remove operation. The following example demonstrates how the effect of both operations. Start with the following resource: ```javascript { "fruits" : [ "apple", "orange", "kiwi", "lime" ], } ``` Apply the following operations on that resource: ```javascript [ { "operation" : "remove", "field" : "/fruits/0", "value" : "" }, { "operation" : "replace", "field" : "/fruits/1", "value" : "pineapple" } ] ``` The PATCH operations are applied sequentially. The `remove` operation removes the first member of that resource, based on its array index, (`fruits/0`), with the following result: ```javascript [ { "fruits" : [ "orange", "kiwi", "lime" ], } ] ``` The second PATCH operation, a `replace`, is applied on the second member (`fruits/1`) of the intermediate resource, with the following result: ```none [ { "fruits" : [ "orange", "pineapple", "lime" ], } ] ``` ## Patch Operation: Transform The `transform` operation changes the value of a field based on a script or some other data transformation command. The following `transform` operation takes the value from the field named `/objects`, and applies the `something.js` script as shown: ```javascript [ { "operation" : "transform", "field" : "/objects", "value" : { "script" : { "type" : "text/javascript", "file" : "something.js" } } } ] ``` ## Patch Operation Limitations Some HTTP client libraries do not support the HTTP PATCH operation. Make sure that the library you use supports HTTP PATCH before using this REST operation. For example, the Java Development Kit HTTP client does not support PATCH as a valid HTTP method. Instead, the method `HttpURLConnection.setRequestMethod("PATCH")` throws `ProtocolException`. Parameters You can use the following parameters. Other parameters might depend on the specific action implementation: * `_prettyPrint=true` Format the body of the response. - `_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 server returns all default values.