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.
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.
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.
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 command - Conditional mandatory; used with the set and validate methods. Supported options are:
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:
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:
|
|
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:
|
Output defaults to JSON if not specified. |
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.
Candidate mode
JSON uses its own private candidate that allows multiple users or services to make simultaneous changes to a configuration.
Logical expressions
For logical expressions, support is provided for the asterisk (‟*”) which can be used to reference all keys within a list.
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"
}