Application Note ENT-AN1126

JSON-RPC

JSON-RPC is a protocol used for remote procedure calls. The messages exchanged in JSON-RPC areJSON encoded data structures. The JSON-RPC protocol has a server role and a client role. The clientinitiates communication by sending a request to the server, and the server processes the request to sendback a response. For more information about the JSON-RPC specification, see http://json-rpc.org/. Forinformation about the general JSON specification, see http://json.org.

Microsemi software includes a JSON-RPC server, and in order to use it, a JSON-RPC client must beprovided. 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 thefollowing additional properties:

• Machine-and human-friendly interface.

• Reliable connections orientated communication provided by the TCP and HTTP messageencapsulation.

• 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 termsof program memory and data memory.

Note: JSON-RPC is not a end user interface intended for human interaction, it is a high level machinefriendly interface. Because of this, the intended audience of this document is developers who arealready familiar with the JSON-RPC technology. It is recommended that users not already familiarwith JSON or JSON-RPC read the short and well written official standards.

Table of Contents

Getting Started with JSON-RPCThe purpose of this section is to get started using JSON-RPC by verifying that the switch software of thedevice 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 beprovided by other technologies. In the default configuration of Microsemi software, this is done using theHTTP protocol and the existing web server. For more information on options for message parsingprotocols, see JSON Integration Models. (see page 21)

The curl application, which is available on most Linux, Unix (and can be downloaded for Windowssystems), can be used to send a JSON-RPC request to the target over the HTTP protocol. The curlapplication is good for initial debugging, but one should not rely on it for building real applications. Almostall programming languages are well suited for integration with built-in or library support for JSON-RPC.The following is an example using curl.

curl http://admin:@target.ip.or.address/json_rpc -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 theJSON-RPC back-end server is integrated. The content of the -d argument is the posted JSON-RPC

Getting Started with JSON-RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

JSON Interface Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8JSON Integration Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

July 2015 1

© 2015 Microsemi Corporation

JSON-RPC 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, "broadcast":"10.99.10.255","reasmMaxSize":65535, "arpRetransmitTime":300

}

}

]

}

The vson Toolcurl is good for the initial debugging, but it is very verbose and not very convenient to use whenexploring the VTSS-JSON-RPC command set. For this reason we have developed a simple consolebased application which allows to easily call JSON-RPC methods and present the result in a humanreadable way. This tool is called vson and it can be downloaded from github using the followingcommand:

$ git clone https://github.com/vtss/json-rpc-util.git After downloading, start by checking that it can run.

$ ./vson --helpUsage: vson [common-options] <command> [<args>] 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 messageCommands:callCall a json RPC function on target using the spec file. update-specDownload the newest spec file from the target, and saveit 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:falseFor more information about how to the use the vson tool, see https://github.com/vtss/json-rpc-util.

22

JSON Interface SpecificationsJSON Interface Specifications

JSON Interface SpecificationsThe Microsemi JSON interface specification is used to document the methods available on the JSONinterface. The Microsemi JSON interface specification is called json_spec. The json_spec is a JSONencoded document with a predefined scheme.

This section is not about the specific interface specification generated on one of the target systems, butrather 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 thefollowing ways:

• Web: It can be downloaded from http://address.or.ip.of.device/json_spec

• JSON-RPC: The same specification can also be retrieved by calling the json-rpc.status.introspection.generic.inventory.get method.

• JSON-RPC (target specific): A variant of the same specification can be retrieved by calling thejson-rpc.status.introspection.specific.inventory.get method. The difference is that thisspecification will only include attributes and methods available on the device where it wasgenerated.

The following sections document the intended use cases for the json_spec they specify how to readthe json_spec (programmatically or a human).

Intended Use-CasesThe following sections list some of the use cases considered by the developers of the json_spec.

Input to Auto-Generate a Client LibraryThe json_spec includes all the information needed to auto-generate a complete client library. The auto-generator determines the language to use for the client library, threading model, blocking/asynccommunication, and potential third-party libraries.

Input to Interface Documentation GeneratorThe json_spec includes all the interfaces needed to generate a complete set of interfacedocumentation. The documentation generator determines the target format, style, and other details.

Figure 1 • JSON Client Library

Figure 2 • JSON MAnagement Interface

json_spec client library generator

client library source

Abstract Interface Software Daemon

Microsemi Switch

Fetches json_spec

JSON-RPC communication

User interacts with the abstract interface

33

JSON-RPC JSON-RPC

CapabilitiesThe JSON interface is enabled on many different targets (a target is a combination of a chip and SWpacket used). Large part of the JSON interface is independent of the target used - but there are caseswhere this is not possible. Typically this is because the underlying HW offers different facilities whichneeds 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 theydepends on. If the users of the JSON-RPC interface only uses one target type, then it may be useful togenerate the target specific version of the json_spec.

Specification of the SpecificationThis section provide a specification of the VTSS JSON interface specification. Users which choose touse the json_spec to auto generate any material from it should read this section carefully.

Top-Level SpecificationThe 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 bymethods

• The methods list is the set of methods available.

{"types":[...], "groups":[...], "methods":[...]}

Type SpecificationA type specification is used to document the semantic of a given type. Types may either be named oranonymous, named types are included in the types list, while anonymous types are declared where theyare used. A type has a base specification and a more elaborated specification that depends on theclass field. The following is an example of the base specification.

{"name":"<name-of-type-goes-here>", "class":"<TypeSpecification|Enum|Struct>", "description":"<description-goes-here>","json-encoding-type":"<Number|String|Boolean|Array|Object|null>",...}

• name is the name of the type. It is optional because it is not used for anonymous types, butinstances in the types list will always include a name. When other types or methods refers to atype they may use this name, or include the type directly as an anonymous type.

• class is the used to specify what family a given type belongs to. Following is a list of thesupported type-classes:

– TypeSpecification is a terminal type meaning that it is not a combination of otherpredefined types. An example of this could be an IP address, which JSON wise is encoded asa string, but in a programming interface should be pared/serialized and represented as adedicated type.

– Enum is a type which to associate string notations to numbers. The JSON interface only usesthe string notation, but programming interfaces may choose to use the number internally.

44

JSON Interface SpecificationsJSON Interface Specifications

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

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

– 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.

TypeSpecificationAn object of type TypeSpecification uses the same schema as the base type. Following is a coupleof

TypeSpecification example objects.

This is the JSON specification of the type vtss_ip_t. In JSON messages it will be encoded as a stringusing the syntax defined in the description field. The client may choose to map this to an alternative typerepresenting 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",}

EnumAn object of type Enum has always added a field called elements which is a list of objects containingthe fields: name and values.

{"name":"<name-of-type-goes-here>", "class":"Enum", "description":"<description-goes-here>", "json-encoding-type":"String", "elements":[{"name":"<name-of-first-element>", "value":"<value-of-first-element>"},{"name":"<name-of-second-element>", "value":"<value-of-second-element>"},...]}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"}]}

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

{"name":"<name-of-first-element>", "type":"<type-of-first-element>", ["description":"<description-of-element>",]

55

JSON-RPC JSON-RPC

["depends-on-capability":"<reference-to-dependency-it-depends-on>"]}Here is an explanation of each field in the element-descriptor:

• name is the name of the element in the struct. When the type is encoded in JSON, the name isthe key-string used in the map.

• type is either a reference to a type in the types list, or an anonymous type declared there. thetype referred to or the anonymous type defines what type to expect.

• description is an optional value that provides a description string for the given element.

• depends-on-capability is an optional value that may provide a reference to a capability. Ifthis attribute is present in an element-descriptor then it means that the given element is onlypresent if capability is true. If it is not present the given element is always present. An elementthat is not present because its associated capability is false for a given target is ignored in a setoperation, and not included in a get operation.

The following example shows what this may look like in a stuct containing four elements where two arealways present while the other two depend on capabilities. For the actual code, seevtss_appl_evc_ece_conf_t in the json_spec.

{"type-name":"vtss_appl_evc_ece_conf_t", "class":"Struct","description":"Example struct - notcomplete","encoding-type":"Object", "elements":[{"name":"NextId", "type":"uint32_t", "description":"The ID of the next ECE."},{"name":"AdvLookup", "type":"vtss_bool_t","description":"Enable advanced ingress lookup.", "depends-on-capability":"HasEceAdvLookup@vtss_appl_evc_capabilities_t"},{"name":"UniPortList", "type":"vtss_port_list_stackable_t", "description":"List of UNI ports for the ECE."},{"name":"SrcMac", "type":"vtss_mac_t","description":"The source MAC address to match.", "depends-on-capability":"HasEceSrcMac@vtss_appl_evc_capabilities_t"}]}The example above is a struct containing four elements, whereof two is always present and twodepends on capabilities.

ArrayAn object of type Array has added the field called type which specifies what type of values is includedin the array. The value of type may either be a reference to a named type, or a directly declaredanonymous type. Here is an example what an array type could look like:

{"class":"Array", "name":"vtss_ifindex_list_t" "encoding-type": "Array", "type":"vtss_ifindex_t"}

TupleAn object of type Tuple is very similar to an object of type Struct only difference is that the name fieldin the element-descriptor is optional, and the encoding-type will always be an array. Here is anexample of a tuple descriptor:

{"class": "Tuple", "encoding-type": "Array", "elements": [

66

JSON Interface SpecificationsJSON Interface Specifications

{"name": "ifindex", "type": "vtss_ifindex_t"},{"name": "prio", "type": "int32_t"}]}

Group SpecificationMethods and groups can be put into groups. A group can have a description that applies to everythingstored in that group. To allow this, groups and methods may identify a group to which they belong. Sucha group is a reference to an object in the groups list. Objects in the groups list have two mandatory fields,group-name and description, and an optional field, parent-group-name.

{"group-name":"<name-of-group>",[,"parent-group-name":"<name-of-parent-group>"] "description":"<description-of-group>"}The following code shows a complete example.{"group-name":"acl.config.global.ace", "description":"The ACLACEconfiguration table."},{"group-name":"acl.config.global.ace.hardware", "parent-group-name":"acl.config.global.ace", "description":"Table ofACEhardware status."}

Method SpecificationA method is defined using the following syntax.

{"method-name":"<name-of-method>", ["group-name":"<name-of-group>",] ["description":"<description-of-method>",]["depends-on-capability":"<reference-to-dependency-it-depends-on>",] "params":[...], "results":[...]}

• method-name is the name of the method.

• name-of-group this is a reference to a group this method belongs to. The description of thegroup should be inherited as the description of the method.

• description is a description of the method. This field is rarely used for methods, but insteadmost methods are documented through a group.

• depends-on-capability if this attribute is present, then it means that this method is onlyimplemented on targets where the given capability evaluates to true. If this attribute is not present,then the method is always implemented ( assuming the module is included on the target).

The following example shows the syntax of the params and results fields, which list argumentspecifications.

{"name":"<name-of-argument>", ["description":"<description-of-argument>",] "type":"<name-of-type>"}{"method-name":"ip.statistics.interface.ipv4.get", "params":[{"name":"ifidx", "type":"vtss_ifindex_t"

77

JSON-RPC JSON-RPC

}], "results":[{"name":"stats", "description":"Interfacestatistics", "type":"vtss_appl_ip_if_status_ip_stat_t"}]}This covers what is currently implemented and supported in the json_spec, but if necessary thisspecification may be changed in future releases. If such changes takes place they should be done in abackwards compatible way, meaning that it will add new fields or maybe remove optional fields. Thismeans that software using this specification should just ignore fields it does not know about.

Backward CompatibilityBackward and forward compatibility ensures the JSON-RPC Client continues communicating with theserver when one of them is updated. Backward compatibility is needed when the server (the MicrosemiCEServices or SMBStaX software) is updated and implements a newer Microsemi JSON specificationwhile the client remains at an older version of the Microsemi JSON specification. Forward compatibility isneeded when the client is updated and now supports a newer version of the Microsemi JSONspecification than the one supported by the server.

Note: Compatibility is a combined effort on the part of both the server and the client; they must both bedesigned to accomplish this. This section describe what has been done at the server side. It is up tothe designers of the client to do their part.

What to ExpectProviding 100% backward and forward compatibility on the entire JSON-RPC interface will make it verydifficult fix bugs and introduce new features. Compatibility is provided on a best-effort basis to ensurethat existing client functionality remains intact.

The following sections outline guidelines used to implement changes.

Major ReworkMajor rework of a module may not be backward compatible. This is only likely to occur when a major newfeature is added. Such changes are documented in the release notes, and the new interface of themodule is given a new name so that all methods need to be renamed. Doing so ensures that the changeis noticed by the client. In some cases, both the new and the old interface may be accessible in atransition release.

EvolutionModules evolve with the addition of new features that are added by extending the existing structures withnew fields or methods. In such cases the clients can be prepared for compatibility by ignoring unknownfields. The server ignores the client's attempt to configure a field in a struct that it does not recognize.If the client tries to call a method on the server that is not implemented it will receive a textitMethodnot found error code -32601.

Compatibility should not be an issue if the client is prepared for such eventualities. Such changes canalways be found by inspecting the differences between the previous and the current version of theMicrosemi JSON specification. Inspecting such differences can be done by using the vtss-json-spec-difftool, which is distributed along with the vson tool.

Bug FixesTypically bugs can be fixed without changing the JSON-RPC interfaces and compatibility should not bean issue. Any necessary changes get categorized as part of the product evolution.

Compatibility ImplementationThe following sections describe the implementation to maintain compatibility, given that target systemshave no knowledge of future versions, clients, or even applications.

88

JSON Integration ModelsJSON Integration Models

MethodsThe target system implements a set of methods corresponding to the current version of the MicrosemiJSON specification. If a client tries to call a method that does not exist, the server responds with amethod not found error. The client needs to recognize unsupported method errors and adapt to thesituation.

Typically, this is a forward compatibility problem that occurs when the client is newer than the server. Inmost cases existing methods are retained and new methods are added.

Structures (JSON Objects)In the JSON-RPC server implementation all fields in structures are considered optional. This means thatthe server ignores a field in a struct that it does not recognize. If the server is missing assignments ofone or more fields in a set/add request then it is uses default values.

For set methods the default values are provided as follows:

• Performing a get request

• Overwriting the values provided by the get request with the new values from the set request

• Calling the C management method to apply the request. This patching is only done at the firstlevel. If nested structures are exposed, this process is not applied recursively.

For add or set-in-write-only-context the process is almost the same, except an internal defaultsmethods is used in place of the get method.

JSON Integration ModelsJSON-RPC is only a protocol for allowing remote procedure calls. It does not define message parsingfacilities, and assumes that this is done by other means. HTTP(s) is the most commonly used messageexchange protocol used along with JSON-RPC, but it is not always the right choice.

Microsemi software already includes support (enabled by default) for running JSON-RPC over HTTP sothat users can focus on the client part.

HTTP(s) may not always be the right message exchange protocol. This topic provides guidance on whento use HTTP(s) as message exchange protocol. It also mentions alternatives to using HTTP(s) formessage exchange.

HTTP(s) as Message ParsingTo use the JSON-RPC server with HTTP(s) as a message exchange protocol, just post the JSON-RPCrequest to the /json_rpc address, and wait for the response.

Note: HTTP client should always use the keep-alive property to allow reuse of the same TCP connectionfor a number of commands. This is especially important when running an eCos based operatingsystem where the process of freeing a file descriptor is delayed, which may lead to a case where nonew connections can be made because all file descriptors are waiting to be released. Thisobservation is tracked in Bug#13335.

Running JSON-RPC over HTTP(s) is a ideal solution if all of the following criteria are met. This istypically the case when using JSON-RPC for remote management systems or other loosely coupledsystems.

• The RPC communication must go through a TCP/IP connection.

Reason for such criteria could be that the RPC communication must be able to go through a IPnetwork, or that the guarantees provided by TCP are needed.

• The security facilities provided by HTTP(s) match the criteria required for the RPCcommunication.

HTTP and HTTPS uses basic authentications, HTTP have no encryption or integrity checks, whilethis is a part of HTTPS for more details on this inspect the actually web server which is used.

Running JSON-RPC over HTTP(s) should not be considered as a possible if any of the followingproperties is needed.

• RPC communication must work when the target has no IP address.

99

JSON-RPC JSON-RPC

• Security facilities provided by HTTP(s) are not good enough.

• The overhead of IP + TCP + HTTP is not acceptable.

• Management traffic must not go through the normal Ethernet connectivity.

If any of these properties is needed, then the JSON-RPC over HTTP(s) can not be used. In this case it ispossible to provide an alternative message exchange protocol, this is discussed in the following section.

Alternate Message Parsing SystemsWhen JSON-RPC over HTTP(s) is not an optimal solution, it is possible to integrate an alternativemessage exchange facility with the desired characteristics. The integration of JSON-RPC over HTTP(s)can be used as an example when enrolling JSON-RPC on top of other facilities. This integration islocated in vtss_appl/json_rpc/json_rpc_platform.cxx in the json_http_handler function. Integrating theJSON-RPC back-end server with a new message exchange facility is accomplished by calling thefollowing C++ method.

namespace vtss { namespace expose { namespace json {vtss::json::Result::Code RootNode::process(str input, ostreamBuf &out);} // namespace json} // namespace expose} // namespace vtssThe methods must be called on the JSON RPC root instance, which is a static variable invtss_appl/json_rpc/ json_rpc_platform.cxx. The method is thread safe, and may be calledfrom a multi-threaded application without taking any precautions.

The input parameter is a reference to the incoming JSON-RPC request, which must be processed. TheJSON-RPC response is written into the out buffer stream.

Candidates for using this facility are dual CPU systems where the message passing should be doneusing dedicated channels, or tightly coupled systems where the requirement of a functional TCP/IPconnection is not possible.

1010

VPPD-03994. 1.2. July 2015

Microsemi makes no warranty, representation, or guarantee regarding the information contained herein orthe suitability of its products and services for any particular purpose, nor does Microsemi assume anyliability whatsoever arising out of the application or use of any product or circuit. The products soldhereunder and any other products sold by Microsemi have been subject to limited testing and should notbe used in conjunction with mission-critical equipment or applications. Any performance specifications arebelieved to be reliable but are not verified, and Buyer must conduct and complete all performance andother testing of the products, alone and together with, or installed in, any end-products. Buyer shall not relyon any data and performance specifications or parameters provided by Microsemi. It is the Buyer'sresponsibility to independently determine suitability of any products and to test and verify the same. Theinformation provided by Microsemi hereunder is provided “as is, where is” and with all faults, and the entirerisk associated with such information is entirely with the Buyer. Microsemi does not grant, explicitly orimplicitly, to any party any patent rights, licenses, or any other IP rights, whether with regard to suchinformation itself or anything described by such information. Information provided in this document isproprietary to Microsemi, and Microsemi reserves the right to make any changes to the information in thisdocument or to any products and services at any time without notice.

Power Matters.TM

Microsemi Corporation (Nasdaq: MSCC) offers a comprehensive portfolio of semiconductorand system solutions for communications, defense & security, aerospace and industrialmarkets. Products include high-performance and radiation-hardened analog mixed-signalintegrated circuits, FPGAs, SoCs and ASICs; power management products; timing andsynchronization devices and precise time solutions, setting the world's standard for time; voiceprocessing devices; RF solutions; discrete components; security technologies and scalableanti-tamper products; Ethernet solutions; Power-over-Ethernet ICs and midspans; as well ascustom design capabilities and services. Microsemi is headquartered in Aliso Viejo, Calif., andhas approximately 3,600 employees globally. Learn more at www.microsemi.com.

Microsemi Corporate HeadquartersOne Enterprise, Aliso Viejo,CA 92656 USA

Within the USA: +1 (800) 713-4113 Outside the USA: +1 (949) 380-6100Sales: +1 (949) 380-6136Fax: +1 (949) 215-4996E-mail: sales.support@microsemi.comwww.microsemi.com

© 2015 Microsemi Corporation. Allrights reserved. Microsemi and theMicrosemi logo are trademarks ofMicrosemi Corporation. All othertrademarks and service marks are theproperty of their respective owners.