REST API examples

This topic demonstrates the examples of PATCH requests that use JsonPatch syntax and the REST API clients developed using different programming tools and languages.

PATCH request examples
Client code examples

PATCH request examples

This section provides examples of using the PATCH request and JsonPatch syntax used in the body of such requests. A patch allows you to change only the selected values of a component. The JsonPatch object is how you specify what type of change you want to make (the operation) and to what attribute (the path).

This example begins with how a typical object looks in JSON format. Here is a realm as retrieved from the server:

{
  "id": "955703509-1",
  "name": "Default",
  "fallbackConfigsPurgeCriteria": {
    "purgeByCountFlag": true,
    "purgeCount": 50,
    "purgeByDaysFlag": true,
    "purgeDays": 90
  },
  "hardwareInventoryPurgeCriteria": {
    "purgeByCountFlag": true,
    "purgeCount": 10,
    "purgeByDaysFlag": false,
    "purgeDays": 0
  },
  "purgeConfigsByDeviceTypes": {},
  "purgeConfigsByTrails": {
    "02C89A1F-A5D2-44B0-AE1E-B714EB0E3FAF": {
      "purgeByCountFlag": true,
      "purgeCount": 5,
      "purgeByDaysFlag": false,
      "purgeDays": 0
    }
  },
  "purgeDevicesByDaysFlag": false,
  "purgeDevicesDays": 0,
  "dynamicFields": [
    {
      "id": "426945997-29",
      "name": "Description",
      "values": [
        "default realm shipped with the system"
      ]
    }
  ]
}

JsonPatch uses the notion of a path to specify which attribute you want to modify. The path is made up of attribute names, map keys, and index values of the parent attributes that contain the target attribute. For example, the path for the name of the realm is /name, since the name attribute is right at the top level. To specify the purge days value for the hardware inventory, the path is /dynamicFields/0/values/0.

Similarly, navigating to the inner elements of maps requires the use of the map key in the path. The path to the purge count value for the running trail (the GUID in the example is for the running trail) is /purgeConfigsByTrails/02C89A1F-A5D2-44B0-AE1E-B714EB0E3FAF/purgeCount.

The following examples show the available PATCH operations and how they use paths. The add, replace, and remove operations are the most useful operations.

Add operation

An example JsonPatch request to add another dynamic field and its value to the preceding realm is as follows:

[{
  "op":"add",
  "path":"/dynamicFields/1",
  "value":{"id":"426945997-12345",
           "values":["value for second dynamic field"]
          }
}]

Replace operation

An example JsonPatch request to enable hardware inventory purging by days in the preceding realm, where two attributes need to be changed (the flag to enable the purging, and the days count) is as follows:

[{
  "op":"replace",
  "path":"/hardwareInventoryPurgeCriteria/purgeByDaysFlag",
  "value":true
},
{
  "op":"replace",
  "path":"/hardwareInventoryPurgeCriteria/purgeDays",
  "value":31
}]

Remove operation

An example JsonPatch request to remove or delete the optional Description dynamic field value in the preceding realm is as follows:

[{
"op":"remove",
"path":"/dynamicFields/0"
}]

Move operation

A move is equivalent to a 'remove' of one value and an 'add' of another. An example JsonPatch request to move the purge criteria for one trail to another trail in the preceding realm is as follows:

[{
  "op":"move",
  "from":"/purgeConfigsByTrails/02C89A1F-A5D2-44B0-AE1E-B714EB0E3FAF",
  "path":"/purgeConfigsByTrails/1D168B48-15CC-416E-AB4A-88E2E7104E2D"
}]

Copy operation

An example JsonPatch request to copy the purge criteria for one trail to another trail in the preceding realm is as follows:

[{
  "op":"copy",
  "from":"/purgeConfigsByTrails/02C89A1F-A5D2-44B0-AE1E-B714EB0E3FAF",
  "path":"/purgeConfigsByTrails/1D168B48-15CC-416E-AB4A-88E2E7104E2D"
}]

Test operation

The test operation makes changes only if an attribute is set to a value. That is, if an attribute is not of the tested value, the entire patch is skipped. An example JsonPatch request to change the Description dynamic field value in the preceding realm only when the realm is named Default is as follows:

[{
  "op":"test",
  "path":"/name",
  "value":"Default"
},
{
  "op" : "replace",
  "path":"/dynamicFields/0/values/0",
  "value":"new Description value"
}]

Client code examples

This section presents examples of REST API clients developed using different programming tools and languages.

Powershell example

Click here to view powershell code.

# for the purposes of this example script 'username' and 'password' are
# embedded. that may not be ideal in practice.
# there is no error trapping included in the example.

$username = "youruser"
$password = "yourSuperSecretPassword"
$service = "https://serverName:portNumber/bca-networks/api"

# ignore certificate errors (only needed if a Certificate Authority is not available)
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

# tell powershell not to default to insecure protocols!
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# make the call to authenticate and get a token for subsequent calls
Write-Host "Logging in..."
$response = Invoke-RestMethod -Method Post -Uri "$service/token" `
         -Body "grant_type=password&username=$username&password=$password" `
         -ContentType "application/x-www-form-urlencoded"
Write-Host "Received response: $response"

# extract the token and token type
$token = $response.access_token
$tokenType = $response.token_type

# example of a follow on call using the token
Write-Host "Getting all devices..."
$response = Invoke-RestMethod -Method Get -Uri "$service/v1.0/devices" `
        -Header @{"Authorization" = "$tokenType $token"}

# print devices to the screen
Write-Host "Retrieved devices: "
$response | Format-List

# logout and invalidate the token
Write-Host "Logging out..."
Invoke-RestMethod -Method Delete -Uri "$service/token" `
        -Header @{"Authorization" = "$tokenType $token"}

# end example

Python example

This example requires that the python Requests library be installed. This library is available at http://python-requests.org.

Click here to view python code.

# for the purposes of this example script 'username' and 'password' are
# embedded. that may not be ideal in practice; would be better to pass them
# in as command line arguments.
# there is no error trapping included in the example.
# there is no certificate verification; this allows the example to work using
# the server's default self-signed certificate only. verification warnings
# are emitted that can be ignored.

import json
import requests

username = "youruser"
password = "yourSuperSecretPassword"
service = "https://serverName:portNumber/bca-networks/api"

# make the call to authenticate and get a token for subsequent calls
print "Logging in..."
headers = {"Content-type": "application/x-www-form-urlencoded"}
data = {"grant_type" : "password",
        "username" : username,
        "password" : password}
response = requests.post(service + "/token", headers=headers, data=data, verify=False)
print "Received response:", response.text

# extract the token and token type
data = response.json()
token = data["access_token"]
tokenType = data["token_type"]

# example of a follow on call using the token
print "Getting all devices..."
headers = {"Authorization": tokenType + " " + token}
response = requests.get(service + "/v1.0/devices", headers=headers, verify=False)

# parse the JSON and print the device names
print "Retrieved devices:"
data = response.json()
for device in data:
    print device["name"]

# logout and invalidate the token
print "Logging out..."
response = requests.delete(service + "/token", headers=headers, verify=False)

# end example