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.
The JSON RPC requires a specific message structure. The jsonrpc version, id, method, and params are required in all requests.
Within these required elements can be additional mandatory and conditional elements; see Table 16.
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. See method options for more information. |
params | Defines a container for any parameters related to the request. The type of parameter is dependent on the method used. See params options for more information. |
Table 17 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 will accept 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. |
Table 18 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:
| |
commands (cont.) | 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. |
Table Note 1: gNMI path specification reference: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-path-conventions.md |
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.
JSON uses its own private candidate that allows multiple users or services to make simultaneous changes to a configuration.
For logical expressions, support is provided for the asterisk (“*”) which can be used to reference all keys within a list.
The following provides JSON examples (both requests and responses) for these method options:
The get method lets you retrieve configuration and state details from the system.
Example 1: Single get with recursive request
Response (single get with recursive)
Example 2: Multiple get request
Response (multiple get)
The set method lets you set a configuration or run operational commands.
Example 1: Multiple set with update and replace request
Response (multiple set)
Example 2: Set method using path keywords request
Response (set using path-keywords)
Example 3: Set using alternative update (specifying a value) request
Response (set using alternative update)
The set method lets you utilize an action delete command to delete nodes or leafs within a configuration.
Example 1: multiple set method delete request
Response (multiple set delete)
The validate method lets you 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.
Example 1: validate a delete request
Response (validate delete)
Example 2: validate a update and replace request
Response (validate update and delete)
The cli method lets you 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.
Example 1: CLI method input request
Response (CLI input)
Example 2: CLI method input request with output formatting
Response (CLI with output formatting)