The JSON-RPC API

The JSON-RPC specification defines the following error code values:

To make server errors easier to read, along the numeric code, we use a type param that yields a literal error token. For all application defined errors, the code is always -32000. It's best to ignore the code and just use the type param.

{"jsonrpc": "2.0",
 "id": 1,
 "method": "login",
 "params":
 {"foo": "joe",
  "bar": "SWkkasE32"}}

which results in:

{"jsonrpc": "2.0",
 "id": 1,
 "error":
 {"code": -32602,
  "type": "rpc.method.unexpected_params",
  "message": "Unexpected params",
  "data":
  {"param": "foo"}}}

The message param is a free text string in English meant for human consumption, which is a one-to-one match with the type param. To remove noise from the examples, this param is omitted from the following descriptions.

An additional method-specific data param may be added to give further details on the error, most predominantly a reason param which is also a free text string in English meant for human consumption. To remove noise from the examples, this param is omitted from the following descriptions. But any additional data params will be noted by each method description.

All methods may return one of the following JSON RPC or application defined errors, in addition to others, specific to each method.

{"type": "rpc.request.parse_error"}
{"type": "rpc.request.invalid"}
{"type": "rpc.method.not_found"}
{"type": "rpc.method.invalid_params", "data": {"param": <string>}}
{"type": "rpc.internal_error"}


{"type": "rpc.request.eof_parse_error"}
{"type": "rpc.request.multipart_broken"}
{"type": "rpc.request.too_big"}
{"type": "rpc.request.method_denied"}


{"type": "rpc.method.unexpected_params", "data": {"param": <string>}}
{"type": "rpc.method.invalid_params_type", "data": {"param": <string>}}
{"type": "rpc.method.missing_params", "data": {"param": <string>}}
{"type": "rpc.method.unknown_params_value", "data": {"param": <string>}}


{"type": "rpc.method.failed"}
{"type": "rpc.method.denied"}
{"type": "rpc.method.timeout"}

{"type": "session.missing_sessionid"}
{"type": "session.invalid_sessionid"}
{"type": "session.overload"}

JSON-RPC runs on top the embedded web server (see "The web server" chapter), which accepts HTTP and/or HTTPS.

The JSON-RPC session ties the client and the server via an HTTP cookie, named "sessionid" which contains a randomly server-generated number. This cookie is not only secure (when the requests come over HTTPS), meaning that HTTPS cookies do not leak over HTTP, but even more importantly this cookie is also http-only, meaning that only the server and the browser (e.g. not the JavaScript code) have access to the cookie. Furthermore, this cookie is a session cookie, meaning that a browser restart would delete the cookie altogether.

The JSON-RPC session lives as long as the user does not request to logout, as long as the user is active within a 30 minute (default value, which is configurable) time frame, as long as there are no severe server crashes. When the session dies, the server will reply with the intention to delete any "sessionid" cookies stored in the browser (to prevent any leaks).

When used in a browser, the JSON-RPC API does not accept cross-domain requests by default, but can be configured to do so via the custom headers functionality in the embedded web server, or by adding a reverse-proxy (see "The web server" chapter).

The embedded server allows for custom headers to be se, in this case CORS headers, like:

Access-Control-Allow-Origin: http://webpage.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, Content-Type, Accept
Access-Control-Request-Method: POST

A server hosted at http://server.com responding with these headers, would mean that the JSON-RPC API can be contacted from a browser which is showing a web page from http://webpage.com, and will allow the browser to make POST requests, with a limited amount of headers and with credentials (i.e. cookies).

This is not enough though, because the browser also needs to be told that your JavaScript code really wants to make a CORS request. A jQuery example would show like this:

// with jQuery
$.ajax({
  type: 'post',
  url: 'http://server.com/jsonrpc',
  contentType: 'application/json',
  data: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'login',
    params: {
      'user': 'joe',
      'passwd': 'SWkkasE32'
    }
  }),
  dataType: 'json',
  crossDomain: true,       // CORS specific
  xhrFields: {             // CORS specific
    withCredentials: true  // CORS specific
  }                        // CORS specific
})

Without this setup, you will notice that the browser will not send the "sessionid" cookie on post-login JSON-RPC calls.

A tagpath is a path pointing to a specific position in a YANG module's schema.

A keypath is a path pointing to specific position in a YANG module's instance.

These kind of paths are used for several of the API methods (e.g. set_value, get_value, subscribe_changes), and could be seen as XPath path specifications in abbreviated format.

Lets look at some examples using the following YANG module as input:

module devices {
    namespace "http://acme.com/ns/devices";
    prefix d;

    container config {
        leaf description { type string; }
        list device {
            key "interface";
            leaf interface { type string; }
            leaf date { type string; }
        }
    }
}

Valid tagpaths:

Valid keypaths:

Note how the prefix is prepended to the first tag in the path. This prefix is compulsory.

The AAA infrastructure can be used to restrict access to library functions using command rules:

<cmdrule xmlns="http://tail-f.com/yang/acm">
  <name>webui</name>
  <context xmlns="http://tail-f.com/yang/acm">webui</context>
  <command>::jsonrpc:: get_schema</command>
  <access-operations>read exec</access-operations>
  <action>deny</action>
</cmdrule>

Note how the command is prefixed with "::jsonrpc:: ". This tells the AAA engine to apply the command rule to JSON-RPC API functions.

You can read more about command rules in "The AAA infrastructure" chapter in this User Guide.

A series of limits are imposed on the load that one session can put on the system.

This reduces the risk that a session takes overs the whole system and brings it into a DoS situation.

The response will include details about the limit that triggered the error.

Known limits:

{}

{"cmds": <array of cmd>}

cmd =
 {"params": <object>,
  "comet_id": <string>,
  "handle": <string>,
  "tag": <"string">,
  "started": <boolean>,
  "stopped": <boolean; should be always false>}

{"th": <integer>,
 "name": <string>,
 "args": <string>,
 "emulate": <boolean, default: false>,
 "width": <integer, default: 80>,
 "height": <integer, default: 24>,
 "scroll": <integer, default: 0>,
 "comet_id": <string>,
 "handle": <string, optional>}

The name param is one on the named commands defined in ncs.conf.

The args param any extra arguments to be provided to the command expect for the ones specified in ncs.conf.

The emulate param specifies if terminal emulation should be enabled.

The width, height, scroll properties define the screen properties.

{"handle": <string>}

A handle to the batch command is returned (equal to handle if provided).

{"handle": <string>,
 "data": <string>}

The handle param is as returned from a call to init_cmd and the data param is what is to be sent to the batch command started with init_cmd.

{}

{"type": "cmd.not_initialized"}

{"handle": <string>}

The handle param is as returned from a call to init_cmd.

{}

{"handle": <string>}

The handle param is as returned from a call to init_cmd.

{}

{"handle": <string>}

The handle param is as returned from a call to init_cmd.

{}

{"handle": <string>}

The handle param is as returned from a call to init_cmd.

{}

{}

{"subscriptions": <array of subscription>}

subscription =
 {"params": <object>,
  "comet_id": <string>,
  "handle": <string>,
  "tag": <"string">,
  "started": <boolean>,
  "stopped": <boolean; should be always false>}

{"comet_id": <string>,
 "handle": <string, optional>,
 "path": <string>}

The path param is a keypath restricting the subscription messages to only be about changes done under that specific keypath.

{"handle": <string>}

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method and the format of that message will be an array of changes of the same type as returned by the subscribe_changes method. See below.

{"type": "db.cdb_operational_not_enabled"}

{"comet_id": <string>,
 "handle": <string, optional>,
 "path": <string>,
 "skip_local_changes": <boolean, default: false>,
 "hide_changes": <boolean, default: false>,
 "hide_values": <boolean, default: false>}

The path param is a keypath restricting the subscription messages to only be about changes done under that specific keypath.

The skip_local_changes param specifies if configuration changes done by the owner of the read-write transaction should generate subscription messages.

The hide_changes and hide_values params specify a lower level of information in subscription messages, in case it is enough to receive just a "ping" or a list of changed keypaths, respectively, but not the new values resulted in the changes.

{"handle": <string>}

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method and the format of that message will be an object such as:

{"db": <"running" | "startup" | "candidate">,
 "user": <string>,
 "ip": <string>,
 "changes": <array>}

The user and ip properties are the username and ip-address of the committing user.

The changes param is an array of changes of the same type as returned by the changes method. See above.

{"th": <integer>,
 "path": <string>,
 "interval": <integer between 0 and 3600>,
 "comet_id": <string>,
 "handle": <string, optional>}

The path param is a keypath pointing to a leaf value.

The interval is a timeout in seconds between when to poll the value.

{"handle": <string>}

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method and the format of is a simple string value.

{"comet_id": <string>,
 "handle": <string, optional>}

{"handle": <string>}

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method and the format of that message will be an object such as:

{"upgrade_state": <"wait_for_init" | "init" | "abort" | "commit">,
 "timeout": <number, only if "upgrade_state" === "wait_for_init">}

{"comet_id": <string>,
 "handle": <string, optional>}

{"handle": <string>}

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method having exact same structure like a JSONRPC response:

{"jsonrpc":"2.0",
 "result":"admin",
 "id":1}

{"jsonrpc": "2.0",
 "id": 1,
 "error":
 {"code": -32602,
  "type": "rpc.method.unexpected_params",
  "message": "Unexpected params",
  "data":
  {"param": "foo"}}}

{"comet_id": <string>,
 "handle": <string, optional>,
 "verbosity": <"normal" | "verbose" | "very_verbose" | "debug", default: "normal">
 "filter_context": <"webui" | "cli" | "netconf" | "rest" | "snmp" | "system" | string, optional>}

The verbosity param specifies the verbosity of the progress trace.

The filter_context param can be used to only get progress events from a specific context For example, if filter_context is set to cli only progress trace events from the CLI are returned.

{"handle": <string>}

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method and the format of that message will be an object such as:

{"timestamp": <string>,
 "duration": <string, optional if end of span>,
 "span-id": <string>,
 "parent-span-id": <string, optional if parent span exists>,
 "trace-id": <string>,
 "session-id": <integer>,
 "transaction-id": <integer, optional if transaction exists>,
 "datastore": <string, optional if transaction exists>,
 "context": <string>,
 "subsystem": <string, optional if in subsystem>,
 "message": <string>,
 "annotation": <string, optional if end of span>,
 "attributes":  <object with key-value attributes, optional>,
 "links":  <array with objects, each containing a trace-id and span-id
 key, optional>}

{"handle": <string>}

The handle param is as returned from a call to subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf or subscribe_upgrade.

{}

{"handle": <string>}

The handle param is as returned from a call to subscribe_cdboper, subscribe_changes, subscribe_messages, subscribe_poll_leaf or subscribe_upgrade.

{}

{"th": <integer>,
 "path": <string>}

The path param is a keypath pointing to data to be created.

{}

{"type": "db.locked"}

{"th": <integer>,
 "path": <string>}

The path param is a keypath pointing to data to be deleted.

{} |
                {"warnings": <array of strings>}

{"type": "db.locked"}

{"th": <integer>,
 "path": <string>}

The path param is a keypath pointing to data to be checked for existence.

{"exists": <boolean>}

{"th": <integer>,
 "path": <string>,
 "choice": <string>}

The path param is a keypath pointing to data that contains the choice leaf given by the choice param.

{"case": <string>}

{"th": <integer>,
 "path": <string>
 "result_as": <"string" | "json" | "json2", default: "string">
 "with_oper": <boolean, default: false>
 "max_size": <"integer", default: 0>}

The path param is a keypath to the configuration to be returned. result_as controls the output format, string for a compact string format, json for json compatible with restconf and json2 for a variant of the restconf json format. max_size sets the maximum size of the data field in kb, set to 0 to disable the limit.

result_as string

{"config": <string>}

result_as json

{"data": <json>}

{"th": <integer>,
 "data": <string>
 "path": <string, default: "/">
 "format": <"json" | "xml", default: "xml">
 "mode": <"create" | "merge" | "replace", default: "merge">}

The data param is the data to be loaded into the transaction. mode controls how the data is loaded into the transaction, analogous with the CLI command load.format informs load about which format data is in. If format is xml the data must be an XML document encoded as a string. If format is json data can either be a JSON document encoded as a string or the JSON data itself.

{}

{"row": <integer>, "message": <string>}

{"th": <integer>,
 "path": <string>,
 "names": <array of string>}

The path param is a keypath pointing to the node and the names param is a list of attribute names that you want to retrieve.

{"attrs": <object of attribute name/value>}

{"th": <integer>,
 "path": <string>,
 "attrs": <object of attribute name/value>}

The path param is a keypath pointing to the node and the attrs param is an object that maps attribute names to their values.

{}

{"th": <integer>,
 "path": <string>,
 "check_default": <boolean, default: false>}

The path param is a keypath pointing to a value.

The check_default param adds is_default to the result if set to true. is_default is set to true if the default value handling returned the value.

{"value": <string>}

{"th": <integer>,
 "path": <string>,
 "check_default": <boolean, default: false>,
 "leafs": <array of string>}

The path param is a keypath pointing to a container. The leafs param is an array of children names residing under the parent container in the YANG module.

The check_default param adds is_default to the result if set to true. is_default is set to true if the default value handling returned the value.

{"values": <array of value/error>}

value  = {"value": <string>, "access": <access>}
error  = {"error": <string>, "access": <access>} |
         {"exists": true, "access": <access>} |
         {"not_found": true, "access": <access>}
access = {"read": true, write: true}

NOTE: The access object has no "read" and/or "write" properties if there are no read and/or access rights.

{"th": <integer>,
 "path": <string>,
 "value": <string | boolean | integer | array | null>,
 "dryrun": <boolean, default: false}

The path param is the keypath to give a new value as specified with the value param.

value can be an array when the path is a leaf-list node.

When value is null, the set_value method acts like delete.

When dryrun is true, this function can be used to test if a value is valid or not.

{} |
                {"warnings": <array of strings>}

{"type": "data.already_exists"}
{"type": "data.not_found"}
{"type": "data.not_writable"}
{"type": "db.locked"}

{"th": <integer>,
 "path": <string>,
 "result_as": <"paths" | "target" | "list-target", default: "paths">}

The path param is a keypath pointing to a leaf with a leafref type.

{"paths": <array of string, a keypath to a leaf>}

{"target": <a keypath to a leaf>}

{"list-target": <a keypath to a list>}

{"th": <integer>,
 "path": <string>,
 "offset": <integer, default: 0>,
 "limit": <integer, default: -1>,
 "starts_with": <string, optional>,
 "skip_grouping": <boolean, default: false>,
 "keys": <object>}

The th param is as returned from a call to new_read_trans or new_write_trans. The path param is a keypath pointing to a leaf with a leafref type. Note: If the leafref is within an action or rpc, th should be created with an action_path.

The offset param is used to skip as many values as it is set to. E.g. an offset of 2 will skip the first 2 values. If not given the value defaults to '0', which means no values are skipped. Offset needs to be a non-negative integer or an "invalid params" error will be returned. An offset that is bigger than the length of the leafref list will result in an "method failed" error being returned.

NOTE: offset used together with limit (see below) can be used repeatedly to paginate the leafref values.

The limit param can be set to limit the number of returned values. E.g. a limit of 5 will return a list with 5 values. If not given the value defaults to '-1', which means no limit. Limit needs to be -1 or a non-negative integer or an "invalid params" error will be returned. A Limit of 0 will result in an empty list being returned

The starts_with param can be used to filter values by prefix.

The skip_grouping param is by default set to false and is only needed to be set to true if if a set of sibling leafref leafs points to a list instance with multiple keys and if get_leafref_values should return an array of possible leaf values instead an array of arrays with possible key value combinations.

The keys param is an optional array of values that should be set if a more than one leafref statement is used within action/rpc input parameters and if they refer to each other using `deref()` or `current()` XPath functions. For example consider this model:

  rpc create-service {
    tailf:exec "./run.sh";
    input {
      leaf name {
        type leafref {
          path "/myservices/service/name";
        }
      }
      leaf if {
        type leafref {
          path "/myservices/service[name=current()/../name]/interfaces/name"
        }
      }
    }
    output {
      leaf result { type string; }
    }
  }

The leaf if refers to leaf name in its XPath expression so to be able to successfully run get_leafref_values on that node you need to provide a valid value for the name leaf using the keys parameter. The keys parameter could for example look like this:

{"/create-service/name": "service1"}

{"values": <array of string>,
 "source": <string> | false}

The source param will point to the keypath where the values originate. If the keypath cannot be resolved due to missing/faulty items in the keys parameter source will be false.

{"th": <integer>,
 "from_path": <string>,
 "to_keys": <array of string>}

The from_path is a keypath pointing out the list entry to be renamed.

The list entry to be renamed will, under the hood, be deleted all together and then recreated with the content from the deleted list entry copied in.

The to_keys param is an array with the new key values. The array must contain a full set of key values.

{}

{"type": "data.already_exists"}
{"type": "data.not_found"}
{"type": "data.not_writable"}

{"th": <integer>,
 "from_path": <string>,
 "to_keys": <array of string>}

The from_path is a keypath pointing out the list entry to be copied.

The to_keys param is an array with the new key values. The array must contain a full set of key values.

Copying between different ned-id versions works as long as the schema nodes being copied has not changed between the versions.

{}

{"type": "data.already_exists"}
{"type": "data.not_found"}
{"type": "data.not_writable"}

{"th": <integer>,
 "from_path": <string>,
 "to_path": <string>,
 "mode": <"first" | "last" | "before" | "after">}

The from_path is a keypath pointing out the list entry to be moved.

The list entry to be moved can either be moved to the first or the last position, i.e. if the mode param is set to first or last the to_path keypath param has no meaning.

If the mode param is set to before or after the to_path param must be specified, i.e. the list entry will be moved to the position before or after the list entry which the to_path keypath param points to.

{}

{"type": "db.locked"}

{"th": <integer>,
 "path": <string>,
 "value": <string>}

The path is a keypath pointing to a leaf-list.

{}

{"th": <integer>
 "path": <string>}

The path parameter is a keypath pointing to a list.

{"count": <integer>}

{"th": <integer>,
 "path": <string>,
 "chunk_size": <integer greater than zero, optional>,
 "start_with": <array of string, optional>,
 "lh": <integer, optional>,
 "empty_list_key_as_null": <boolean, optional>}

The th parameter is the transaction handle.

The path parameter is a keypath pointing to a list. Required on first invocation - optional in following.

The chunk_size parameter is the number of requested keys in the result. Optional - default is unlimited.

The start_with parameter will be used to filter out all those keys that do not start with the provided strings. The parameter supports multiple keys e.g. if the list has two keys, then start_with can hold two items.

The lh (list handle) parameter is optional (on the first invocation) but must be used in following invocations.

The empty_list_key_as_null parameter controls whether list keys of type empty are represented as the name of the list key (default) or as `[null]`.

{"keys": <array of array of string>,
 "total_count": <integer>,
 "lh": <integer, optional>}

Each invocation of get_list_keys will return at most chunk_size keys. The returned lh must be used in following invocations to retrieve next chunk of keys. When no more keys are available the returned lh will be set to `-1`.

On the first invocation lh can either be omitted or set to `-1`.

{"th": <integer>,
 "xpath_expr": <string, optional if path is given>,
 "path": <string, keypath, optional if xpath_expr is given>,
 "selection": <array of xpath expressions, optional>
 "chunk_size": <integer greater than zero, optional>
 "initial_offset": <integer, optional>,
 "sort", <array of xpath expressions, optional>,
 "sort_order": <"ascending" | "descending", optional>,
 "include_total": <boolean, default: true>,
 "context_node": <string, keypath, optional>,
 "result_as": <"string" | "keypath-value" | "leaf_value_as_string", default: "string">}

The xpath_expr param is the primary XPath expression to base the query on. Alternatively, one can give a keypath as the path param, and internally the keypath will be translated into an XPath expression.

A query is a way of evaluating an XPath expression and returning the results in chunks. The primary XPath expression must evaluate to a node-set, i.e. the result. For each node in the result a selection Xpath expression is evaluated with the result node as its context node.

Note: The terminology used here is as defined in http://en.wikipedia.org/wiki/XPath.

For example, given this YANG snippet:

list interface {
  key name;
  unique number;
  leaf name {
    type string;
  }
  leaf number {
    type uint32;
    mandatory true;
  }
  leaf enabled {
    type boolean;
    default true;
  }
}

The xpath_expr could be `/interface[enabled='true']` and selection could be `{ "name", "number" }`.

Note that the selection expressions must be valid XPath expressions, e.g. to figure out the name of an interface and whether its number is even or not, the expressions must look like: `{ "name", "(number mod 2) == 0" }`.

The result are then fetched using run_query, which returns the result on the format specified by result_as param.

There are two different types of result:

This means that care must be taken so that the combination of selection expressions and return types actually yield sensible results (for example `1 + 2` is a valid selection XPath expression, and would result in the string 3 when setting the result type to string - but it is not a node, and thus have no keypath-value.

It is possible to sort the result using the built-in XPath function `sort-by()` but it is also also possible to sort the result using expressions specified by the sort param. These expressions will be used to construct a temporary index which will live as long as the query is active. For example to start a query sorting first on the enabled leaf, and then on number one would call:

$.post("/jsonrpc", {
  jsonrpc: "2.0",
  id: 1,
  method: "start_query",
  params:  {
    th: 1,
    xpath_expr: "/interface[enabled='true']",
    selection: ["name", "number", "enabled"],
    sort: ["enabled", "number"]
  }
})
    .done(...);

The context_node param is a keypath pointing out the node to apply the query on; only taken into account when the xpath_expr uses relatives paths. Lack of a context_node, turns relatives paths into absolute paths.

The chunk_size param specifies how many result entries to return at a time. If set to 0 a default number will be used.

The initial_offset param is the result entry to begin with (1 means to start from the beginning).

{"qh": <integer>}

A new query handler handler id to be used when calling run_query etc

{"qh": <integer>}

The qh param is as returned from a call to "start_query".

{"position": <integer>,
 "total_number_of_results": <integer>,
 "number_of_results": <integer>,
 "chunk_size": <integer greater than zero, optional>,
 "result_as": <"string" | "keypath-value" | "leaf_value_as_string">,
 "results": <array of result>}

result = <string> |
         {"keypath": <string>, "value": <string>}

The position param is the number of the first result entry in this chunk, i.e. for the first chunk it will be 1.

How many result entries there are in this chunk is indicated by the number_of_results param. It will be 0 for the last chunk.

The chunk_size and the result_as properties are as given in the call to start_query.

The total_number_of_results param is total number of result entries retrieved so far.

The result param is as described in the description of start_query.

{"qh": <integer>}

The qh param is as returned from a call to start_query.

{}

{"qh": <integer>}

The qh param is as returned from a call to "start_query".

{}

{}

{"db": <"startup" | "running" | "candidate">}

The db param specifies which datastore to lock.

{}

{"type": "db.locked", "data": {"sessions": <array of string>}}

The `data.sessions` param is an array of strings describing the current sessions of the locking user, e.g. an array of "admin tcp (cli from 192.245.2.3) on since 2006-12-20 14:50:30 exclusive".

{"db": <"startup" | "running" | "candidate">}

The db param specifies which datastore to unlock.

{}

{}

{"comet_id": <string>}

[{"handle": <integer>,
  "message": <a context specific json object, see example below>},
 ...]

{"type": "comet.duplicated_channel"}

{"operation": <"capabilities" | "customizations" | "models" | "user" | "version" | "all" | "namespaces", default: "all">}

The operation param specifies which system setting to get:

{"user:" <string>,
 "models:" <array of YANG modules>,
 "version:" <string>,
 "customizations": <array of customizations>,
 "capabilities":
 {"rollback": <boolean>,
  "copy_running_to_startup": <boolean>,
  "exclusive": <boolean>,
  "confirmed_commit": <boolean>
 },
 "namespaces": <object of YANG modules prefix/namespace>}

The above is the result if using the all operation.

{"id": <integer>}

The id param is the id of the JSON-RPC method to be aborted.

{}

{"th": <integer>,
 "xpath_expr": <string>}

The xpath_expr param is the XPath expression to be evaluated.

{"value": <string>}

{"to": <string>,
 "message": <string>}

The to param is the user name of the user to send the message to and the message param is the actual message.

NOTE: The username "all" will broadcast the message to all users.

{}

{"comet_id": <string>,
 "handle": <string, optional>}

<string>

A handle to the subscription is returned (equal to handle if provided).

Subscription messages will end up in the comet method and the format of these messages depend on what has happened.

When a new user has logged in:

{"new_user": <integer, a session id to be used by "kick_user">
 "me": <boolean, is it myself?>
 "user": <string>,
 "proto": <"ssh" | "tcp" | "console" | "http" | "https" | "system">,
 "ctx": <"cli" | "webui" | "netconf">
 "ip": <string, user's ip-address>,
 "login": <string, login timestamp>}

When a user logs out:

{"del_user": <integer, a session id>,
 "user": <string>}

When receiving a message:

{"sender": <string>,
 "message": <string>}

{"rollbacks": <array of rollback>}

rollback =
 {"nr": <integer>,
  "creator": <string>,
  "date": <string>,
  "via": <"system" | "cli" | "webui" | "netconf">,
  "comment": <string>,
  "label": <string>}

The nr param is a rollback number to be used in calls to load_rollback etc.

The creator and date properties identify the name of the user responsible for committing the configuration stored in the rollback file and when it happened.

The via param identifies the interface that was used to create the rollback file.

The label and comment properties is as given calling the methods set_comment and set_label on the transaction.

{"nr": <integer>}

<string, rollback file in curly bracket format>

{"nr": <integer>}

{}

{"th": <integer>,
 "nr": <integer>,
 "path": <string>,
 "selective": <boolean, default: false>}

The nr param is a rollback number returned by get_rollbacks.

The path param is a keypath that restrict the rollback to be applied only to a subtree.

The selective param, false by default, can restrict the rollback process to use only the rollback specified by nr, rather than applying all known rollbacks files starting with the latest down to the one specified by nr.

{}

{"th": <integer>,
 "path": <string, optional>

A path is a tagpath/keypath pointing into a specific sub-tree of a YANG module.

{"description": <string>}

{"th": <integer>,
 "namespace": <string, optional>,
 "path": <string, optional>,
 "levels": <integer, default: -1>,
 "insert_values": <boolean, default: false>,
 "evaluate_when_entries": <boolean, default: false>,
 "stop_on_list": <boolean, default: false>,
 "cdm_namespace": <boolean, default: false>}

One of the properties namespace or path must be specified.

A namespace is as specified in a YANG module.

A path is a tagpath/keypath pointing into a specific sub-tree of a YANG module.

The levels param limits the maximum depth of containers and lists from which a JSON schema should be produced (-1 means unlimited depth).

The insert_values param signals that instance data for leafs should be inserted into the schema. This way the need for explicit forthcoming calls to get_elem are avoided.

The evaluate_when_entries param signals that schema entries should be included in the schema even though their "when" or "tailf:display-when" statements evaluate to false, i.e. instead a boolean evaluated_when_entry param is added to these schema entries.

The stop_on_list param limits the schema generation to one level under the list when true.

The cdm_namespace param signals inclusion of cdm-namespace entries where appropriate.

{"meta":
 {"namespace": <string, optional>,
  "keypath": <string, optional>,
  "prefix": <string>,
  "types": <array of type>},
 "data": <array of child>}

type = <array of {<string, type name with prefix>: <type_stack>}>

type_stack = <array of type_stack_entry>

type_stack_entry =
 {"bits": <array of string>, "size": <32 | 64>} |
 {"leaf_type": <type_stack>, "list_type": <type_stack>} |
 {"union": <array of type_stack>} |
 {"name": <primitive_type | "user_defined">,
  "info": <string, optional>,
  "readonly": <boolean, optional>,
  "facets": <array of facet, only if not primitive type>}

primitive_type =
 "empty" |
 "binary" |
 "bits" |
 "date-and-time" |
 "instance-identifier" |
 "int64" |
 "int32" |
 "int16" |
 "uint64" |
 "uint32" |
 "uint16" |
 "uint8" |
 "ip-prefix" |
 "ipv4-prefix" |
 "ipv6-prefix" |
 "ip-address-and-prefix-length" |
 "ipv4-address-and-prefix-length" |
 "ipv6-address-and-prefix-length" |
 "hex-string" |
 "dotted-quad" |
 "ip-address" |
 "ipv4-address" |
 "ipv6-address" |
 "gauge32" |
 "counter32" |
 "counter64" |
 "object-identifier"

facet_entry =
 {"enumeration": {"label": <string>, "info": <string, optional>}} |
 {"fraction-digits": {"value": <integer>}} |
 {"length": {"value": <integer>}} |
 {"max-length": {"value": <integer>}} |
 {"min-length": {"value": <integer>}} |
 {"leaf-list": <boolean>} |
 {"max-inclusive": {"value": <integer>}} |
 {"max-length": {"value": <integer>}} |
 {"range": {"value": <array of range_entry>}} |
 {"min-exclusive": {"value": <integer>}} |
 {"min-inclusive": {"value": <integer>}} |
 {"min-length": {"value": <integer>}} |
 {"pattern": {"value": <string, regular expression>}} |
 {"total-digits": {"value": <integer>}}

range_entry =
 "min" |
 "max" |
 <integer> |
 [<integer, min value>, <integer, max value>]

child =
 {"kind": <kind>,
  "name": <string>,
  "qname": <string, same as "name" but with prefix prepended>,
  "info": <string>,
  "namespace": <string>,
  "xml-namespace": <string>,
  "is_action_input": <boolean>,
  "is_action_output": <boolean>,
  "is_cli_preformatted": <boolean>,
  "is_mount_point": <boolean>
  "presence": <boolean>,
  "ordered_by": <boolean>,
  "is_config_false_callpoint": <boolean>,
  "key": <boolean>,
  "exists": <boolean>,
  "value": <string | number | boolean>,
  "is_leafref": <boolean>,
  "leafref_target": <string>,
  "when_targets": <array of string>,
  "deps": <array of string>
  "hidden": <boolean>,
  "default_ref":
  {"namespace": <string>,
   "tagpath": <string>
  },
  "access":
  {"create": <boolean>,
   "update": <boolean>,
   "delete": <boolean>,
   "execute": <boolean>
  },
  "config": <boolean>,
  "readonly": <boolean>,
  "suppress_echo": <boolean>,
  "type":
  {"name": <primitive_type>,
   "primitive": <boolean>
  }
  "generated_name": <string>,
  "units": <string>,
  "leafref_groups": <array of string>,
  "active": <string, active case, only if "kind" is "choice">,
  "cases": <array of case, only of "kind" is "choice">,
  "default": <string | number | boolean>,
  "mandatory": <boolean>,
  "children": <children>
 }

kind =
 "module" |
 "access-denies" |
 "list-entry" |
 "choice" |
 "key" |
 "leaf-list" |
 "action" |
 "container" |
 "leaf" |
 "list" |
 "notification"

case_entry =
 {"kind": "case",
  "name": <string>,
  "children": <array of child>
 }

This is a fairly complex piece of JSON but it essentially maps what is seen in a YANG module. Keep that in mind when scrutinizing the above.

The meta param contains meta-information about the YANG module such as namespace and prefix but it also contains type stack information for each type used in the YANG module represented in the data param. Together with the meta param, the data param constitutes a complete YANG module in JSON format.

{"th": <integer>,
 "group_name": <string>

The group_name param is as defined by a "hidden" statement in a YANG module.

{}

{"th": <integer>,
 "group_name": <string>,
 "passwd": <string>}

The group_name param is as defined by a "hidden" statement in a YANG module.

The passwd param is a password needed to hide the data that has been adorned with a "hidden" statement. The password is as defined in the ncs.conf file.

{}

Method takes no parameters.

<key-value object>

result = {"module-name": "module-prefix"}

{"th": <integer>,
 "path": <string>,
 "params": <json, optional>
 "format": <"normal" | "bracket" | "json", default: "normal">,
 "comet_id": <string, optional>,
 "handle": <string, optional>,
 "details": <"normal" | "verbose" | "very_verbose" | "debug", optional>}

Actions are as specified in th YANG module, i.e. having a specific name and a well defined set of parameters and result. the path param is a keypath pointing to an action or rpc in and the params param is a JSON object with action parameters.

The format param defines if the result should be an array of key values or a pre-formatted string on bracket format as seen in the CLI. The result is also as specified by the YANG module.

Both a comet_id and handle need to be provided in order to receive notifications.

The details param can be given together with comet_id and handle in order to get progress trace for the action. details specifies the verbosity of the progress trace. After the action has been invoked, the comet method can be used to get the progress trace for the action. If the details param is omitted progress trace will be disabled.

NOTE This method is often used to call an action that uploads binary data (e.g. images) and retrieving them at a later time. While retrieval is not a problem, uploading is a problem, because JSON-RPC request payloads have a size limitation (e.g. 64 kB). The limitation is needed for performance concerns because the payload is first buffered, before the JSON string is parsed and the request is evaluated. When you have scenarios that need binary uploads, please use the CGI functionality instead which has a size limitation that can be configured, and which is not limited to JSON payloads, so one can use streaming techniques.

<string | array of result | key-value object>

result = {"name": <string>, "value": <string>}

{"type": "action.invalid_result", "data": {"path": <string, path to invalid result>}}

{}

{"user": <string>, "passwd": <string>, "ack_warning": <boolean, default: false>}

There are two versions of the login method. The method with no parameters only invokes Package Authentication, since credentials can be supplied with the whole HTTP request. The method with parameters is used when credentials may need to be supplied with the method parameters, this method invokes all authentication methods including Package Authentication.

The user and passwd are the credentials to be used in order to create a user session. The common AAA engine in NSO is used to verify the credentials.

If the method fails with a warning, the warning needs to be displayed to the user, along with a checkbox to allow the user to acknowledge the warning. The acknowledgement of the warning translates to setting ack_warning to true.

{"warning": <string, optional>}

NOTE The response will have a `Set-Cookie` HTTP header with a sessionid cookie which will be your authentication token for upcoming JSON-RPC requests.

The warning is a free-text string that should be displayed to the user after a successful login. This is not to be mistaken with a failed login that has a warning as well. In case of a failure, the user should also acknowledge the warning, not just have it displayed for optional reading.

{"challenge_id": <string>, "challenge_prompt": <string>}

NOTE A challenge response will have a challenge_id and challenge_prompt which needs to be responded to with an upcoming JSON-RPC challenge_response requests.

{"challenge_id": <string>, "response": <string>, "ack_warning": <boolean, default: false>}

The challenge_id and response is the multi factor response to be used in order to create a user session. The common AAA engine in NSO is used to verify the response.

If the method fails with a warning, the warning needs to be displayed to the user, along with a checkbox to allow the user to acknowledge the warning. The acknowledgement of the warning translates to setting ack_warning to true.

{"warning": <string, optional>}

NOTE The response will have a `Set-Cookie` HTTP header with a sessionid cookie which will be your authentication token for upcoming JSON-RPC requests.

The warning is a free-text string that should be displayed to the user after a successful challenge response. This is not to be mistaken with a failed challenge response that has a warning as well. In case of a failure, the user should also acknowledge the warning, not just have it displayed for optional reading.

None.

{}

{"user": <string | number>}

The user param is either the username of a logged in user or session id.

{}

{"key": <string>}

The key param for which to get the stored data for. Read more about the session store in the put_session_data method.

{"value": <string>}

{"key": <string>,
 "value": <string>}

The key param is the unique key for which the data in the value param is to be stored.

{}

{"key": <string>}

The key param for which all session data will be erased. Read more about the session store in the put_session_data method.

{}

None.

{"trans": <array of transaction>}

transaction =
 {"db": <"running" | "startup" | "candidate">,
  "mode": <"read" | "read_write", default: "read">,
  "conf_mode": <"private" | "shared" | "exclusive", default: "private">,
  "tag": <string>,
  "th": <integer>}

{"db": <"startup" | "running" | "candidate", default: "running">,
 "mode": <"read" | "read_write", default: "read">,
 "conf_mode": <"private" | "shared" | "exclusive", default: "private">,
 "tag": <string>,
 "action_path": <string>,
 "th": <integer>,
 "on_pending_changes": <"reuse" | "reject" | "discard", default: "reuse">}

The conf_mode param specifies which transaction semantics to use when it comes to lock and commit strategies. These three modes mimics the modes available in the CLI.

The meaning of private, shared and exclusive have slightly different meaning depending on how the system is configured; with a writable running, startup or candidate configuration.

private (*writable running enabled*) - Edit a private copy of the running configuration, no lock is taken.

private (*writable running disabled, startup enabled*) - Edit a private copy of the startup configuration, no lock is taken.

exclusive (*candidate enabled*) - Lock the running configuration and the candidate configuration and edit the candidate configuration.

exclusive (*candidate disabled, startup enabled*) - Lock the running configuration (if enabled) and the startup configuration and edit the startup configuration.

shared (*writable running enabled, candidate enabled*) - Is a deprecated setting.

The tag param is a way to tag transactions with a keyword, so that they can be filtered out when you call the get_trans method.

The action_path param is a keypath pointing to an action or rpc. Use action_path when you need to read action/rpc input parameters.

The th param is a way to create transactions within other read_write transactions.

The on_pending_changes param decides what to do if the candidate already has been written to, e.g. a CLI user has started a shared configuration session and changed a value in the configuration (without committing it). If this parameter is omitted the default behavior is to silently reuse the candidate. If "reject" is specified the call to the "new_trans" method will fail if the candidate is non-empty. If "discard" is specified the candidate is silently cleared if it is non-empty.

{"th": <integer>}

A new transaction handler id

{"type": "trans.confirmed_commit_in_progress"}
{"type": "db.locked", "data": {"sessions": <array of string>}}

The `data.sessions` param is an array of strings describing the current sessions of the locking user, e.g. an array of "admin tcp (cli from 192.245.2.3) on since 2006-12-20 14:50:30 exclusive".

{"th": <integer>}

{}

{"th": <integer>}

{}

{"th": <integer>}

{}

{"th": <integer>}

{"modified": <boolean>}

{"th": <integer>},
 "output": <"compact" | "legacy", default: "legacy">

The output parameter controls the result content. legacy format include old and value for all operation types even if their value is undefined. undefined values are represented by an empty string. compact format excludes old and value if their value is undefined.

{"changes": <array of change>}

change =
 {"keypath": <string>,
  "op": <"created" | "deleted" | "modified" | "value_set">,
  "value": <string,>,
  "old": <string>
 }

The value param is only interesting if op is set to one of modified or value_set.

The old param is only interesting if op is set to modified.

{"th": <integer>}

{}

or

{"warnings": <array of warning>}

warning = {"paths": <array of string>, "message": <string>}

{"type": "trans.resolve_needed", "data": {"users": <array string>}}

The data.users param is an array of conflicting usernames.

{"type": "trans.validation_failed", "data": {"errors": <array of error>}}

error = {"paths": <array of string>, "message": <string>}

The data.errors param points to a keypath that is invalid.

{"th": <integer>}

{"conflicts:" <array of conflicts>}

conflict =
 {"keypath": <string>,
  "op": <"created" | "deleted" | "modified" | "value_set">,
  "value": <string>,
  "old": <string>}

The value param is only interesting if op is set to one of created, modified or value_set.

The old param is only interesting if op is set to modified.

{"th": <integer>}

{}

{"th": <integer>}

{"comet_id": <string, optional>}

{"handle": <string, optional>}

{"details": <"normal" | "verbose" | "very_verbose" | "debug", optional>}

{"flags": <flags, default: []>}
flags = <array of string or bitmask>

The comet_id, handle, and details params can be given together in order to get progress tracing for the validate_commit operation. The same comet_id can also be used to get the progress trace for any coming commit operations. In order to get progress tracing for commit operations, these three parameters have to be provided with the validate_commit operation. The details parameter specifies the verbosity of the progress trace. After the operation has been invoked, the comet method can be used to get the progress trace for the operation.

See the commit method for available flags.

NOTE: If you intend to pass flags to the commit method, it is recommended to pass the same flags to validate_commit since they may have an effect during the validate step.

{}

or

{"warnings": <array of warning>}

warning = {"paths": <array of string>, "message": <string>}

Same as for the validate_trans method.

{"th": <integer>}

{}

{"th": <integer>,
 "timeout": <integer, default: 0>,
 "release_locks": <boolean, default: true>,
 "rollback-id": <boolean, default: true>}

The commit with a timeout parameter represents a confirmed commit.

If rollback-id is set to true the response will include the id of the rollback file created during the commit if any.

Commit behaviour can be changed via an extra flags param:

{"flags": <flags, default: []>}

flags = <array of string or bitmask>

The flags param is a list of flags that can change the commit behavior:

For backwards compatibility, the flags param can also be a bit mask with the following limit values:

NOTE: Must be preceded by a call to validate_commit

NOTE: The transaction handler is deallocated as a side effect of this method

Successful commit without any arguments

{}

Successful commit with rollback-id=true

{"rollback-id": {"fixed": 10001}}

Successful commit with commit-queue=async

{"commit_queue_id": <integer>}

The commit_queue_id is returned if the commit entered the commit queue, either by specifying commit-queue=async or by enabling it in the configuration.

{"type": "trans.confirmed_commit_in_progress"}

{"type": "trans.confirmed_commit_is_only_valid_for_candidate"}

{"type": "trans.confirmed_commit_needs_config_writable_through_candidate"}

{"type": "trans.confirmed_commit_not_supported_in_private_mode"}

{}

{}

{"trans": <array of trans>}

trans =
 {"db": <"startup" | "running" | "candidate", default: "running">,
  "conf_mode": <"private" | "shared" | "exclusive", default: "private">,
  "th": <integer>
 }

{"db": <"startup" | "running" | "candidate", default: "running">,
 "conf_mode": <"private" | "shared" | "exclusive", default: "private">
 "on_pending_changes": <"reuse" | "reject" | "discard", default: "reuse">}

See 'new_trans' for semantics of the parameters and specific errors.

The on_pending_changes param decides what to do if the candidate already has been written to, e.g. a CLI user has started a shared configuration session and changed a value in the configuration (without committing it). If this parameter is omitted the default behavior is to silently reuse the candidate. If "reject" is specified the call to the "new_webui_trans" method will fail if the candidate is non-empty. If "discard" is specified the candidate is silently cleared if it is non-empty.

{"th": <integer>}

A new transaction handler id

{"th": <integer>,
 "name": <string>}

The name param is the name of the template to extract variables from.

{"template_variables": <array of string>}

{"status": <"installable" | "installed" | "loaded" | "all", default: "all">}

The status param specifies which package status to list:

{"packages": <array of key-value objects>}

{"th": <integer>, "flags": <flags}

See the commit method for available flags.

See result for method commit.