JSON-RPC - Microchip Technology

Application Note ENT-AN1126

JSON-RPC

JSON-RPC is a protocol used for remote procedure calls. The messages exchanged in JSON-RPC are

JSON encoded data structures. The JSON-RPC protocol has a server role and a client role. The client

initiates communication by sending a request to the server, and the server processes the request to send

back a response. For more information about the JSON-RPC specification, see . For

information about the general JSON specification, see .

Microsemi software includes a JSON-RPC server, and in order to use it, a JSON-RPC client must be

provided. This application note provides the information needed to build such a client.

JSON-RPC provides a high-level interface that is the functional equivalent of ICLI or SNMP with the

following additional properties:

?

Machine-and human-friendly interface.

?

Reliable connections orientated communication provided by the TCP and HTTP message

encapsulation.

?

RPC orientated protocol, which fits into most programming languages.

?

Can be implemented in practically any language and needs only a very limited foot-print in terms

of program memory and data memory.

Note: JSON-RPC is not a end user interface intended for human interaction, it is a high level machine

friendly interface. Because of this, the intended audience of this document is developers who are

already familiar with the JSON-RPC technology. It is recommended that users not already familiar

with JSON or JSON-RPC read the short and well written official standards.

Table of Contents

Getting Started with JSON-RPC

JSON Interface Specifications . .

Backward Compatibility . . . . .

JSON Integration Models . . . .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

1

3

8

9

Getting Started with JSON-RPC

The purpose of this section is to get started using JSON-RPC by verifying that the switch software of the

device has JSON-RPC enabled and that it is functional.

JSON-RPC requires a message parsing protocol that is not part of the JSON-RPC standard, but must be

provided by other technologies. In the default configuration of Microsemi software, this is done using the

HTTP protocol and the existing web server. For more information on options for message parsing

protocols, see JSON Integration Models. (see page 21)

The curl application, which is available on most Linux, Unix (and can be downloaded for Windows

systems), can be used to send a JSON-RPC request to the target over the HTTP protocol. The curl

application is good for initial debugging, but one should not rely on it for building real applications. Almost

all programming languages are well suited for integration with built-in or library support for JSON-RPC.

The following is an example using curl.

curl -d \

'{"method":"ip.status.interface.ipv4.get",\ "params":[],"id":"0"}'

In this example, the curl application logs in to the device as the admin with no password.

target.ip.or.address is a placeholder for the actual address and /json_rpc is the URL where the

JSON-RPC back-end server is integrated. The content of the -d argument is the posted JSON-RPC

July 2015

? 2015 Microsemi Corporation

1

JSON-RPC

request message, and the result that is printed on the screen. The following is an example of the result,

with line breaks and indentations inserted to improve readability.

{

"id":"0", "error":null, "result":[

{

"key":"VLAN 1", "val":{

"address":"10.99.10.12",

"prefix":24,

"reasmMaxSize":65535, "arpRetransmitTime":300

}

}

]

}

"broadcast":"10.99.10.255",

The vson Tool

curl is good for the initial debugging, but it is very verbose and not very convenient to use when

exploring the VTSS-JSON-RPC command set. For this reason we have developed a simple console

based application which allows to easily call JSON-RPC methods and present the result in a human

readable way. This tool is called vson and it can be downloaded from github using the following

command:

$ git clone

After downloading, start by checking that it can run.

$ ./vson --help

Usage: vson [common-options] [] Common-options:

-d, --dut ADDRESS Hostname or IP address of the DUT

-u, --dut-username USERUsername for the HTTP session

-p, --dut-password PASSPassword for the HTTP session

--spec-cache=[SPEC-FILE]Use a cached spec file. If no file is specified it will

try use ~/.vtss-json-rpc.spec

-c Use ~/.vtss-json-rpc.spec as cached spec file

-h, --helpShow this message

Commands:

callCall a json RPC function on target using the spec file. update-spec

Download the newest spec file from the target, and save

it as a cache.

specInspect the spec file.

grepList type and methods who's name matches the pattern.

To call a JSON-RPC method using the vson the call sub command is used, as follows:

$ ./vson -c -d 10.99.10.2 call port.status.get "Gi 1/1"

Calling port.status.get:

Link:

true

Fdx:

true

Fiber:false

Speed:speed1G

SFPType:none

SFPVendorName:

SFPVendorPN:

SFPVendorRev:

LossOfSignal:true

TxFault:true

Present:false

For more information about how to the use the vson tool, see .

2

JSON Interface Specifications

JSON Interface Specifications

The Microsemi JSON interface specification is used to document the methods available on the JSON

interface. The Microsemi JSON interface specification is called json_spec. The json_spec is a JSON

encoded document with a predefined scheme.

This section is not about the specific interface specification generated on one of the target systems, but

rather an abstract specification of the Microsemi JSON interface specification.

The json_spec is normally distributed directly on the devices and it can be accessed in one of the

following ways:

?

Web: It can be downloaded from

?

JSON-RPC: The same specification can also

rpc.status.introspection.generic.inventory.get method.

?

JSON-RPC (target specific): A variant of the same specification can be retrieved by calling the

json-rpc.status.introspection.specific.inventory.get method. The difference is that this

specification will only include attributes and methods available on the device where it was

generated.

be

retrieved

by

calling

the

json-

The following sections document the intended use cases for the json_spec they specify how to read

the json_spec (programmatically or a human).

Intended Use-Cases

The following sections list some of the use cases considered by the developers of the json_spec.

Input to Auto-Generate a Client Library

The json_spec includes all the information needed to auto-generate a complete client library. The autogenerator determines the language to use for the client library, threading model, blocking/async

communication, and potential third-party libraries.

client library

generator

json_spec

client library

source

Figure 1 ? JSON Client Library

Input to Interface Documentation Generator

The json_spec includes all the interfaces needed to generate a complete set of interface

documentation. The documentation generator determines the target format, style, and other details.

Abstract

Interface

Software

Daemon

Fetches json_spec

Microsemi

Switch

JSON-RPC communication

User interacts with the

abstract interface

Figure 2 ? JSON MAnagement Interface

3

JSON-RPC

Capabilities

The JSON interface is enabled on many different targets (a target is a combination of a chip and SW

packet used). Large part of the JSON interface is independent of the target used - but there are cases

where this is not possible. Typically this is because the underlying HW offers different facilities which

needs to be exposed to the user. In such cases capabilities is used to inform what is available.

A capability is just a get method which return an object with a set of booleans. If a given boolean is true,

then the given capability is present on the target, otherwise it is not.

Attributes and methods which depends on a capability will provide a reference to the capability they

depends on. If the users of the JSON-RPC interface only uses one target type, then it may be useful to

generate the target specific version of the json_spec.

Specification of the Specification

This section provide a specification of the VTSS JSON interface specification. Users which choose to

use the json_spec to auto generate any material from it should read this section carefully.

Top-Level Specification

The json_spec consists of an object containing three lists: types, groups, and methods.

?

The types list is the combined set of all named types used by all types and methods mentioned.

?

The groups list contains groups declarations which are referred to either by other groups or by

methods

?

The methods list is the set of methods available.

{

"types":[

...

], "groups":[

...

], "methods":[

...

]

}

Type Specification

A type specification is used to document the semantic of a given type. Types may either be named or

anonymous, named types are included in the types list, while anonymous types are declared where they

are used. A type has a base specification and a more elaborated specification that depends on the

class field. The following is an example of the base specification.

{

"name":"",

"class":"",

"description":"",

"json-encoding-type":"",

...

}

? name is the name of the type. It is optional because it is not used for anonymous types, but

instances in the types list will always include a name. When other types or methods refers to a

type they may use this name, or include the type directly as an anonymous type.

?

4

class is the used to specify what family a given type belongs to. Following is a list of the

supported type-classes:

¨C

TypeSpecification is a terminal type meaning that it is not a combination of other

predefined types. An example of this could be an IP address, which JSON wise is encoded as

a string, but in a programming interface should be pared/serialized and represented as a

dedicated type.

¨C

Enum is a type which to associate string notations to numbers. The JSON interface only uses

the string notation, but programming interfaces may choose to use the number internally.

JSON Interface Specifications

¨C

Struct is an aggregation of other types (named or anonymous).

¨C

Array is a replication of a single type in zero to many instances.

¨C

Tuple is a sorted collection of zero to many different types.

?

description is used to document how the specific types must be interpreted and used.

?

json-encoding-type specifies how the given type is encoded in the JSON domain.

TypeSpecification

An object of type TypeSpecification uses the same schema as the base type. Following is a couple

of

TypeSpecification example objects.

This is the JSON specification of the type vtss_ip_t. In JSON messages it will be encoded as a string

using the syntax defined in the description field. The client may choose to map this to an alternative type

representing a IPv4 address.

{

"name":"vtss_ip_t",

"class":"TypeSpecification",

"description":"Ipv4 address encoded as \"a.b.c.d\", where a-d is a base-10

human readable integer in the range [0-255]",

"encoding-type":"String",

}

The following example is the JSON specification of the type vtss_ipv6_t.

{

"name":"vtss_ipv6_t",

"class":"TypeSpecification",

"description":"An Ipv6 address represented as human readable test as specified

in RFC5952",

"json-encoding-type":"String",

}

Enum

An object of type Enum has always added a field called elements which is a list of objects containing

the fields: name and values.

{

"name":"", "class":"Enum",

"description":"", "json-encoding-type":"String",

"elements":[

{"name":"", "value":""},

{"name":"", "value":""},

...

]

}

The following is an example of an Enum object.

{

"type-name":"vtss_appl_ece_rule_t", "class":"Enum",

"description":"The ECE rule type.", "encoding-type":"String", "elements":[

{"name":"both", "value":"0"},

{"name":"rx", "value":"1"},

{"name":"tx", "value":"2"}

]

}

Struct

An object of type Struct has added a list called elements which always contains a set of elementdescriptor. An element-descriptor is an object that looks like this:

{

"name":"",

"type":"",

["description":"",]

5

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download