Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Modify Entities Using API

Introduction

The PATCH verb is a type of HTTP request method for applying partial changes to an existing resource.

To standardize the way the server expects these changes, JSON PATCH standard has been created on top of PATCH verb.

It works by supplying a body parameter containing a list of operations describing the changes that needs to be applied in the specified order to the specified resource.

The following are the supported operations:

  • add
  • remove
  • replace
  • move
  • copy

API

PATCH will be available at the same route of PUT verb.

Updating Name, Description, Timestamp...

The "add" and "replace" operations are interchangeable in this scenario because they will update the field to the new value.

If we start from the simplest entity that we can create:

{

    "name": "Test Entity #1"

}

and then we apply this patch operation:

[

    { "op": "add", "path": "name", "value": "New name" }

]

The entity will look like:

{

    "name": "New Name"

}

It is possible to send many operations at once and execute them one after the other.

In the sample below the patch request will initialize/update name, description and timestamp fields as specified in the array. 

[

    { "op": "add", "path": "/name", "value": "New name" },

    { "op": "add", "path": "/description", "value": "New description" },

    { "op": "add", "path": "/timestamp", "value": "2018-04-18T00:00" }

]

Updating Tags

Patch allow also to manage even arrays like tags.

Note that before adding an item into an array it needs to be initialized first.

In the sample below we are first initializing the tags array and then adding on tag at a time.

[

    { "op": "add", "path": "/tags", "value": [] },

    { "op": "add", "path": "/tags/-", "value": "tag1" },

    { "op": "add", "path": "/tags/-", "value": "tag2" }

]

It is also possible to directly define the array items like in the sample below.

[

    { "op": "add", "path": "/tags", "value": [tag1", tag2", tag3"] }

]

Updating Coordinates

Initialize location of an entity can be done using the following

[

    {

        "op": "add",

        "path": "location",

        "value":{

            "type":"Point",

            "coordinates": [9.2343, 40.23434]

        }

    }

]

While update is possible with just

[

    {

        "op": "replace",

        "path": "location/coordinates",

        "value":[8.23423, 31.23423]

    }

]

Updating Attributes

Attributes can be initialized using the following command

[

    {

        "op": "add",

        "path": "attributes",

        "value": {

            "key_number_1":{

                "label": "Key #1",

                "value":"value1"

            },

            "key_number_2":{

                "label": "Key #2",

                "value":true

            },

            "key_number_3":{

                "label": "Key #3",

                "value":{

                    "complex_object": true

                }

            }

        }

    }

]

It is possible to replace the value of one of the existing attributes by doing

[

    {

        "op": "replace",

        "path": "attributes/key_number_1/value",

        "value": "new value"

    }

]

As described in this issue page the add of a single attribute from scratch will not work untill Asp.Net Core 2.1 is release

https://github.com/aspnet/JsonPatch/issues/96

 

  • Was this article helpful?