Raritan / Server Technology Xerus™ PDU JSON-RPC API
Xerus™ JSON-RPC Software Development Kit

Welcome to the Xerus™ JSON-RPC Software Development Kit! This archive contains libraries and documentation for developing programs using the JSON-RPC interface of Raritan power products.

Raritan devices expose their full functionality via a JSON-RPC API. This API can be used for remote control, mass configuration or integration with other systems. All interfaces are formally defined in IDL (interface definition language) files.

What is JSON-RPC?

JSON-RPC is a HTTP-based remote prodecure call (RPC) protocol. Client programs send JSON-encoded requests to a URL on the server. The server performs the requested operation and responds with either a response object or an error object, also encoded in JSON.

For example, a client might send the following request object to the /snmp URL to invoke the getConfiguration method:

{ "jsonrpc": "2.0", "method": "getConfiguration", "params": {}, "id": 3 }

The server will respond with the following object containing the active configuration of the SNMP agent:

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

All JSON-RPC requests must be directed to a URL on the device's HTTPS service. The path component of this URL is called resource ID (RID). See Well-Known Resource IDs for a list of resource IDs that serve as entry points into the API.

Important Interfaces

The following pages introduce the interfaces required for some typical use cases:

Client Libraries and Examples

This SDK includes client libraries for using the Xerus™ JSON-RPC API in programs written in the Perl, Python and Java programming languages. Those libraries are described on the following pages. Additionally, examples are given for sending raw JSON-RPC requests using the cURL command-line HTTP client.

Please note that some examples given may not be applicable to the product this API documentation was released for. Examples use the API of PDU. Nevertheless the principles of the API usage is identical for either product.

Language Binding Feature Matrix

The following special features are supported by the provided language bindings:

Language Basic Auth Session Auth Synchronous API Asynchronous API Multi-Version Bulk RPC
Perl yes yes yes no yes no
Python yes yes yes no no yes
Java yes yes yes yes yes yes
C# / .NET yes yes yes yes yes yes

Formal Interface Defintion

All interfaces, methods and data structures are formally defined in IDL files. These definitions are the source for the provided client libraries.

See Rules and Mechanism for Mapping Xerus™-IDL to JSON-RPC for more details about IDL and its mapping to JSON-RPC.

See IDL Interface Versioning for details about interface version numbers.

Device-side Scripting With Lua

Recent versions of the Raritan firmware include an interpreter for the Lua programming language. This interpreter can be used to execute user-provided scripts directly on the device without need for a client PC. Lua scripts can access the IDL API, both on the unit they're running on and on remote units. Please see LuaPLC for more details.