Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
Rules and Mechanism for Mapping Xerus™-IDL to JSON-RPC

# Scope

Xerus™ devices provide a remote interface. The interface is a REST architecture and utilizes JSON-RPC version 2.0 for formatting messages sent to and received from the device. This document defines how formal Xerus™-IDL is mapped to JSON-RPC.

# Mapping Rules

## Type Mapping

IDL types are mapped to JSON value types as follows:

IDL Type | JSON Representation
--- | ---
boolean | `true` or `false`
byte | number
int | number
long | number
float | number
double | number
string | string
typecode | string
time | number — seconds elapsed since the time's epoch (mostly Unix - midnight UTC of January 1, 1970)
enumeration | number — index of the enumeration value (0-based)
structure | object with one member per structure element
vector | array
map | array of objects, each with two members: `key` — the entry's key, `value` — the entry's value
interface | object with two members: `rid` — resource identifier string, `type` — typecode of the most derived type
valueobject | object with two members: `value` — object with one member per element, `type` — typecode of the most derived type

## Interface version Mapping

Interface versions as specified in IDL files (e.g. `SessionManager_2_0_1`) are not mapped to the protocol as such as interface identifiers are not directly part of any protocol message. However, the interface version is part of the type information which is sent along with object references. Clients may use type information and hence version information to select a compatible proxy for a received object reference.

See IDL Interface Versioning for more details about interface versions.

Interface changes between firmware releases are documented in the file Changelog.txt.

## Method Mapping

IDL method calls are mapped to JSON-RPC as follows:

In JSON-RPC Request:

- method name: member `method` of request object
- in-parameters: member `params` of request object, an object with one member per parameter
- out-parameters: not mapped
- return value: not mapped

Example (request of security.Security.setDefaultAdminAccountPassword):

{
"jsonrpc": "2.0",
"method": "setDefaultAdminAccountPassword",
"params": {
"password": "my_pass",
"disableStrongPasswordReq": true
},
"id": 123
}

In JSON-RPC Response:

- method name: not mapped
- in-parameters: not mapped
- out-parameters: member `result` of response object, an object with one member per parameter
- return value: special member `_ret_` of member `result` of response object
- system errors or exceptions: member `error` of response object

Example (result from devsettings.Snmp.getConfiguration):

{
"jsonrpc": "2.0",
"result": {
"_ret_": {
"v2enable": true,
"v3enable": false,
"readComm": "public",
"writeComm": "",
"sysContact": "",
"sysName": "",
"sysLocation": ""
}
},
"id": 456
}

# Call Execution

Xerus™-JSON-RPC uses HTTP-POST or HTTPS-POST requests. The JSON-RPC request is put into POST data, the JSON-RPC response is delivered in the HTTP/HTTPS response.

The HTTP URL includes an object reference which uniquely identifies a resource that implements a particular IDL interface. There are well-known references that must be used in initial requests. All well-known object references are defined in Well-Known Resource IDs.

JSON-RPC responses may contain references to other objects. References returned by the device are "opaque", they do not use the well-known name. The `rid` element of those opaque references must be used as URI in requests directed to the referenced resource.

# Authentication

All RPC calls must be authenticated with valid user credentials. Xerus™ supports two methods for passing those credentials:

- HTTP Basic Authentication
- Session Authentication

## Basic Authentication

For HTTP basic authentication the user name and password must be included in the `Authorization` header of every HTTP request. The contents of the header line must be the keyword `Basic` followed by a base64-encoded string containing the user name and password, separated by a colon. For instance, to authenticate a request with login/password = admin/raritan the following header must be sent:

Authorization: Basic YWRtaW46cmFyaXRhbg==

Note
  see Default Credentials for your product

## Session Authentication

For Session-based authentication the client contacts the session manager at `/session` to open a new session. The initial `newSession` request must be sent with basic authentication. The server generates a 128-bit session token and sends it to the client. Subsequent requests can be authenticated by including a `X-SessionToken` HTTP header with the secret session token:

X-SessionToken: 9e520dc84533342cd034b49550969e7f

The session token remains valid until the session expires or is closed. A session expires 30 seconds after the last request.

- see: `session.SessionManager`

# Bulk RPC

For complex client programs which perform a great number of requests it is not feasible to send a separate HTTP request for every JSON-RPC method call. There is a significant performance overhead, particularly when using HTTPS. To reduce that overhead it is possible to combine multiple JSON-RPC requests into a single HTTP request using the BulkRequest interface at `/bulk`.

A bulk request is performed by calling the performBulk method with a vector of resource IDs and JSON-RPC request objects. The method returns a list of HTTP status codes and JSON-RPC response objects.

Example (sent to https://my-device/bulk):

{
"jsonrpc": "2.0",
"method": "performBulk",
"params": {
"requests": [
// First request: Firmware::getVersion()
{ "rid": "/firmware",
"json": { "jsonrpc": "2.0", "method": "getVersion", "params": {}, "id": 1 } },
// Second request: EventLog::clear()
{ "rid": "/eventlog",
"json": { "jsonrpc": "2.0", "method": "clear", "params": {}, "id": 2 } }
]
},
"id": 123
}

Response:

{
"jsonrpc": "2.0",
"result": {
"responses": [
// First response: HTTP 200 (OK), firmware version
{ "statcode": 200,
"json": { "jsonrpc": "2.0", "result": { "_ret_": "3.1.0.5-23456" }, "id": 1 } },
// Second response: HTTP 200 (OK), no return value
{ "statcode": 200,
"json": { "jsonrpc": "2.0", "result": null, "id": 2 } }
]
},
"id": 123
}

The Java language binding uses bulk RPC by default when using the asynchronous API. The Perl binding does not support bulk RPC yet.

- see: `bulkrpc.BulkRequest`