Replace element

Description

Replace a top level element from an array or key from an object in a resource. The request returns the updated resource. If the resource has a test value this can be modified by using the is_test parameter.

Request

HTTP Method: POST

Parameter Description
resource_id The ID of the live resource.
key The object key to replace if replacing from an object.
index The index of the element to replace if replacing from an array (with indexes starting at 0).
value The new value to replace the existing element with
if_value Optional When provided, the operation only proceeds if the current value at the specified key (for objects) or index (for arrays) matches this value. If the value does not match, a 422 error is returned with the current value included in the response. Supports any JSON value (string, number, boolean, object, array). A null value is treated the same as omitting the parameter (unconditional operation).
is_test Optional Boolean value stating if the test resource should be used

Sample request

Sample request for an array element

curl -X POST \
  https://<<META.tenant.domain>>/api/v1/global_resources/<<resource_id>>/replace \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "index": "0",
        "value": "new-value"
    }'

Sample request for an object key

curl -X POST \
  https://<<META.tenant.domain>>/api/v1/global_resources/<<resource_id>>/replace \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "key": "foo",
        "value": "new-value"
    }'

Sample request for conditional replacement (compare-and-swap)

curl -X POST \
  https://<<META.tenant.domain>>/api/v1/global_resources/<<resource_id>>/replace \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "key": "count",
        "value": 6,
        "if_value": 5
    }'

Examples

Replacing an element in an array

Given a resource with value:

["alice", "bob", "charlie"]

Sending { "index": "1", "value": "eve" } updates the resource to:

["alice", "eve", "charlie"]

Replacing a key in an object

Given a resource with value:

{ "city": "Cork", "country": "Ireland" }

Sending { "key": "city", "value": "Galway" } updates the resource to:

{ "city": "Galway", "country": "Ireland" }

Conditional replacement (compare-and-swap)

Given a resource with value:

{ "count": 5 }

Sending { "key": "count", "value": 6, "if_value": 5 } updates the resource to:

{ "count": 6 }

If count were any other value, the request would return a 422 error with the current value and the resource would remain unchanged.

Response

A successful request will return the updated resource value.

Sample response

{ "city": "Galway", "country": "Ireland" }
Was this helpful?