JSON interface

The SR Linux provides a JSON-based Remote Procedure Call (RPC) for both CLI commands and configuration. The JSON API allows the operator to retrieve and set the configuration and state, and provide a response in JSON format. This JSON-RPC API models the CLI implemented on the system.

If output from a command cannot be displayed in JSON, the text output is wrapped in JSON to allow the application calling the API to retrieve the output. During configuration, if a TCP port is in use when the JSON-RPC server attempts to bind to it, the commit fails. The JSON-RPC supports both normal paths, as well as XPATHs.

JSON message structure

The JSON RPC requires a specific message structure. The jsonrpc version, ID, method, and params are required in all requests. For example:

{
"jsonrpc": "2.0",
"id": 0,
"method": "get",
"params": {
}
}

Within these required elements can be additional mandatory and conditional elements, as described in the following table.

Table 1. Required JSON request structure

Required request elements

Description

jsonrpc

Version, which must be ‟2.0”. No other JSON RPC versions are currently supported.

id

Client-provided integer. The JSON RPC responds with the same ID, which allows the client to match requests to responses when there are concurrent requests.

method

Defines the method accessed with the JSON RPC. Supported options are get, set, and cli.

params

Defines a container for any parameters related to the request. The type of parameter is dependent on the method used.

method options

The following table defines supported JSON RPC method options.

Table 2. JSON RPC method options

Method option

Description

get

Used to retrieve configuration and state details from the system. The get method can be used with candidate, running, and state datastores, but cannot be used with the tools datastore.

set

Used to set a configuration or run operational transaction. The set method can be used with the candidate and tools datastores.

validate

Used to verify that the system accepts a configuration transaction before applying it to the system.

cli

Used to run CLI commands. The get and set methods are restricted to accessing data structures via the YANG models, but the cli method can access any commands added to the system via python plug-ins or aliases.

params options

The following table defines valid JSON RPC params options.

Table 3. JSON RPC params options

params option

Descriptions

commands - Mandatory. List of commands used to execute against the called method. Multiple commands can be executed with a single request. Supported commands are:

  • action

  • path

  • path-keywords

  • datastore

  • recursive

  • include-field-defaults

action command - Conditional mandatory; used with the set and validate methods. Supported options are:

  • replace — Replaces the entire configuration within a specific context with the supplied configuration; equivalent to a delete/update.

  • update — Updates a leaf or container with the specified value.

  • delete — Deletes a leaf or container. All children beneath the parent are removed from the system.

Note: When the action command is used with the tools datastore, update is the only supported option.

path command - Mandatory with the get, set and validate methods. This value is a string that follows the gNMI path specification1 in human-readable format:

  • ‟/” separates nodes

  • keys are specified using [<key-name>=<key-value>]

  • if key-value contains ‟]”, it must be escaped (‟\” before the ”]”

  • fields end with ‟.” or ‟,value>”

Example: /interface[name=mgmt0]

path-keywords command - Optional; used to substitute named parameters with the path field. More than one keyword can be used with each path.

datastore command - Optional; selects the datastore to perform the method against. Supported options are:

  • candidate — Used to change the configuration of the system with the get, set, and validate methods; default datastore is used if the datastore parameter is not provided.

  • running — Used to retrieve the active configuration with the get method.

  • state — Used to retrieve the running (active) configuration along with the operational state.

  • tools — Used to perform operational tasks on the system; only supported with the update action command and the set method.

recursive command - Optional; a Boolean used to retrieve children underneath the specific path. The default = true.

include-field-defaults command - Optional; a Boolean used to show all fields, regardless if they have a directory configured or are operating at their default setting. The default = false.

output-format - Optional. Defines the output format as:

  • json

  • text

  • table

Output defaults to JSON if not specified.
1 gNMI path specification reference: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-path-conventions.md

JSON responses

The JSON RPC returns one entry for each command that was executed. For methods that contain non-response (other than acknowledging the command), a response is returned, but with an empty list.

When the cli method is used, each executed command returns an individual response.

Compressed JSON responses using gzip

If a client request specifies to use HTTP compression, the JSON RPC server compresses the responses using gzip.

Candidate mode

JSON uses its own private exclusive candidate that restricts other users or services from making simultaneous changes to a configuration. If another exclusive session is already active, any commits to the configuration using the JSON-RPC set method fail with an error.

The JSON-RPC server uses the private exclusive candidate name jsonrpc-<n>, where <n> is a 32-bit number starting at 1 that increments for every request received, but resets on a JSON-RPC server restart.

Logical expressions

For logical expressions, support is provided for the asterisk (‟*”) which can be used to reference all keys within a list.

Interactive CLI commands

Interactive CLI commands that either run until receiving an indication to end the process, or that require interactive user input typically cannot be called using non-interactive interfaces such as JSON-RPC's CLI method.

To allow you to perform critical tasks related to service validation and network testing using programmable interfaces, SR Linux allows non-interactive interfaces to call the following interactive CLI commands:

  • ping and ping6 when the -c argument is included to ensure finite execution time
  • traceroute and traceroute6
  • bash cat <file path>
  • bash echo <content> <file>

JSON examples

The following provides JSON examples (both requests and responses) for these method options:

JSON get examples

The get method allows you to retrieve configuration and state details from the system. The following examples are shown:

  • get method using the path, datastore, and recursive commands with the recursive option set to true (to retrieve children underneath the specific path)

  • multiple get request where multiple commands are executed with a single request

Single get with recursive request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "get",
  "params": {
    "commands": [
      {
        "path": "/interface[name=mgmt0]",
        "datastore": "state",
        "recursive": true
      }
    ]
  }
}

Response (single get with recursive)

{
  "result": [
    {
      "name": "mgmt0",
      "admin-state": "enable",
      "mtu": 1514,
      "ifindex": 524304383,
      "oper-state": "up",
      "last-change": "2019-07-12T16:53:39.291Z",
      "statistics": {
        "in-octets": "4545395",
        "in-unicast-pkts": "1178",
        "in-broadcast-pkts": "130",
        "in-multicast-pkts": "27560",
        "in-discards": "0",
        "in-errors": "0",
        "in-unknown-protos": "0",
        "in-fcs-errors": "0",
        "out-octets": "1735990",
        "out-unicast-pkts": "1125",
        "out-broadcast-pkts": "38",
        "out-multicast-pkts": "9187",
        "out-discards": "0",
        "out-errors": "0",
        "carrier-transitions": "1"
      },
      "ethernet": {
        "hw-mac-address": "02:42:AC:12:00:05",
        "statistics": {
          "in-mac-control-frames": "0",
          "in-mac-pause-frames": "0",
          "in-oversize-frames": "0",
          "in-jabber-frames": "0",
          "in-fragment-frames": "0",
          "in-crc-errors": "0",
          "out-mac-control-frames": "0",
          "out-mac-pause-frames": "0"
        }
      },
      "subinterface": [
        {
          "index": 0,
          "admin-state": "enable",
          "ip-mtu": 1500,
          "ifindex": 524288000,
          "oper-state": "up",
          "last-change": "2019-07-12T16:53:39.291Z",
          "ipv4": {
            "allow-directed-broadcast": false,
            "dhcp-client": true,
            "address": [
              {
                "ip-prefix": "172.18.0.5/24",
                "origin": "dhcp"
              }
            ],
            "srl_nokia-interfaces-nbr:arp": {
              "timeout": 14400,
              "neighbor": [
                {
                  "ipv4-address": "172.18.0.1",
                  "link-layer-address": "02:42:90:06:D7:26",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-15T21:37:28.987Z"
                },
                {
                  "ipv4-address": "172.18.0.2",
                  "link-layer-address": "02:42:AC:12:00:02",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T00:44:17.673Z"
                },
                {
                  "ipv4-address": "172.18.0.3",
                  "link-layer-address": "02:42:AC:12:00:03",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T01:20:48.600Z"
                },
                {
                  "ipv4-address": "172.18.0.4",
                  "link-layer-address": "02:42:AC:12:00:04",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T01:20:48.597Z"
                },
                {
                  "ipv4-address": "172.18.0.6",
                  "link-layer-address": "02:42:AC:12:00:06",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T01:20:48.599Z"
                }
              ]
            }
          },
          "ipv6": {
            "dhcp-client": true,
            "address": [
              {
                "ip-prefix": "2001:172:18::5/80",
                "origin": "dhcp",
                "status": "preferred"
              },
              {
                "ip-prefix": "fe80::42:acff:fe12:5/64",
                "origin": "link-layer",
                "status": "preferred"
              }
            ],
            "srl_nokia-interfaces-nbr:neighbor-discovery": {
              "dup-addr-detect": true,
              "reachable-time": 30,
              "stale-time": 14400
            }
          }
        }
      ]
    }
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

Multiple get request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "get",
  "params": {
    "commands": [
      {
        "path": "/interface[name=mgmt0]",
        "datastore": "state",
        "recursive": false
      },
      {
        "path": "/interface[name=ethernet-1/10]",
        "datastore": "state",
        "recursive": false
      }
    ]
  }
}

Response (multiple get)

{
  "result": [
    {
      "name": "mgmt0",
      "admin-state": "enable",
      "mtu": 1514,
      "ifindex": 524304383,
      "oper-state": "up",
      "last-change": "2019-07-12T16:53:39.291Z"
    },
    {
      "name": "ethernet-1/10",
      "description": "dut2-dut4-2",
      "admin-state": "enable",
      "mtu": 9232,
      "ifindex": 180223,
      "oper-state": "up",
      "last-change": "2019-07-12T16:54:15.602Z"
    }
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

JSON set examples

The set method allows you to set a configuration or run operational commands. The following examples are shown:

  • multiple set method using update and replace

  • set method using path-keywords

  • set method using an alternative update

Multiple set with update and replace request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
     "commands": [
        {
           "action": "update",
           "path": "/interface[name=mgmt0]/description:my-description"
        },
        {
           "action": "replace",
           "path": "/interface[name=mgmt0]/subinterface[index=0]/description:my-subdescription"
        }
     ]
  }
}

Response (multiple set)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

set using path keywords request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
    "commands": [
      {
        "action": "update",
        "path": "/interface[name={name}]/description:my-description",
        "path-keywords": {
          "name": "mgmt0"
        }
      },
      {
        "action": "replace",
        "path": "/interface[name={name}]/subinterface[index={index}]/description:my-subdescription",
        "path-keywords": {
          "name": "mgmt0",
          "index": "0"
        }
      }
    ]
  }
}

Response (set using path-keywords)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

set using alternative update (specifying a value) request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
    "commands": [
      {
        "action": "update",
        "path": "/interface[name=mgmt0]",
        "value": {
          "description": "my-description",
          "subinterface": {
            "index": "0",
            "description": "my-subdescription"
          }
        }
      }
    ]
  }
}

Response (set using alternative update)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

JSON delete example

The set method allows you to use an action delete command to delete nodes or leafs within a configuration.

The following example shows a multiple set delete request to delete the specified paths.

Multiple set method delete request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
    "commands": [
      {
        "action": "delete",
        "path": "/interface[name=mgmt0]/description"
      },
      {
        "action": "delete",
        "path": "/interface[name=mgmt0]/subinterface[index=0]/description"
      }
    ]
  }
}

Response (multiple set delete)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

JSON validate example

The validate method allows you to verify that the system will accept a configuration transaction before applying it to the system. The ‛delete’, ‛replace’, and ‛update’ actions can be used with the validate method. The following examples are shown:

  • validate request to delete a specified path.

  • validate request to update and replace a specified path.

validate a delete request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "validate",
  "params": {
    "commands": [
      {
        "action": "delete",
        "path": "/interface[name=mgmt0]/description"
      }
    ],
    "datastore": "candidate"
  }
}

Response (validate delete)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

validate an update and replace request

{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "validate",
    "params": {
        "commands": [
            {
                "action": "update",
                "path": "/interface[name=mgmt0]/description:my-description"
            },
            {
                "action": "replace",
                "path": "/interface[name=mgmt0]/subinterface[index=0]
 /description:my-subdescription"
            }
        ]
    }
}

Response (validate update and delete)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

JSON CLI example

The cli method allows you to run CLI commands. While get and set methods are restricted to accessing data structures in the YANG models, the cli method can access commands that have been added to the system using python plug-ins.

The following examples are shown:

  • JSON cli command request.

  • JSON cli command requesting the output format as text.

    You can optionally define these output formats: json, text, or table. JSON is the default.

CLI method input request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "cli",
  "params": {
    "commands": [
      "enter candidate",
      "info interface mgmt0"
    ]
  }
}

Response (CLI input)

{
  "result": [
    {},
    {
      "interface": [
        {
          "name": "mgmt0",
          "description": "my-description",
          "admin-state": "enable",
          "subinterface": [
            {
              "index": 0,
              "description": "my-subdescription",
              "admin-state": "enable",
              "ipv4": {
                "dhcp-client": true
              },
              "ipv6": {
                "dhcp-client": true
              }
            }
          ]
        }
      ]
    }
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

CLI method input request with output formatting

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "cli",
  "params": {
    "commands": [
      "enter candidate",
      "info interface mgmt0"
    ],
    "output-format": "text"
  }
}

Response (CLI with output formatting)

{
  "result": [
    "",
    "    interface mgmt0 {\n      description my-description\n        
admin-state enable\n              subinterface 0 {\n            
description my-subdescription\n   admin-state enable\n       ipv4 {\n
dhcp-client true\n                }\n                        ipv6 {\n 
dhcp-client true\n                }\n                        }\n      }\n"
  ],
  "id": 0,
  "jsonrpc": "2.0"
}