1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Raritan / Server Technology Xerus™ PDU JSON-RPC API: Rules and Mechanism for Mapping Xerus™-IDL to JSON-RPC</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Raritan / Server Technology Xerus™ PDU JSON-RPC API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Rules and Mechanism for Mapping Xerus™-IDL to JSON-RPC </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md__home_builds_gitlab_builds_QjAyd6bt_0_gitlab_main_firmware_mkdist_tmp_build_pdu_px2_final_documentation_json_rpc_api_idl2jsonrpc_mapping"></a></p>
<h1><a class="anchor" id="autotoc_md6"></a>
Scope</h1>
<p>Xerus™ devices provide a remote interface. The interface is a <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a> architecture and utilizes <a href="http://json-rpc.org/">JSON-RPC version 2.0</a> for formatting messages sent to and received from the device. This document defines how formal Xerus™-IDL is mapped to JSON-RPC.</p>
<h1><a class="anchor" id="autotoc_md7"></a>
Mapping Rules</h1>
<h2><a class="anchor" id="autotoc_md8"></a>
Type Mapping</h2>
<p>IDL types are mapped to <a href="http://www.json.org">JSON</a> value types as follows:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">IDL Type </th><th class="markdownTableHeadNone">JSON Representation </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">boolean </td><td class="markdownTableBodyNone"><code>true</code> or <code>false</code> </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">int </td><td class="markdownTableBodyNone">number </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">long </td><td class="markdownTableBodyNone">number </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">float </td><td class="markdownTableBodyNone">number </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">double </td><td class="markdownTableBodyNone">number </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">string </td><td class="markdownTableBodyNone">string </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">time </td><td class="markdownTableBodyNone">number containing number of seconds since the start of the Unix epoch (midnight UTC of January 1, 1970) </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">enumeration </td><td class="markdownTableBodyNone">number representing the index of the enumeration value (0-based) </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">structure </td><td class="markdownTableBodyNone">object containing one element per structure member </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">vector </td><td class="markdownTableBodyNone">array </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">map </td><td class="markdownTableBodyNone">array of objects, each containing two elements: 'key' for the entry's key, 'value' for the entry's value. </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">interface </td><td class="markdownTableBodyNone">object containing two elements: 'rid' contains the object identifier, 'type' contains the most derived interface type </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md9"></a>
Interface version Mapping</h2>
<p>Interface versions as specified in IDL-File (e.g. <code>NumericSensor_1_0_1</code>) 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.</p>
<p>See <a class="el" href="idl_versions.html">IDL Interface Versioning</a> for more details about interface versions.</p>
<p>Interface changes between firmware releases are documented in the file <a href="Changelog.txt">Changelog.txt</a>.</p>
<h2><a class="anchor" id="autotoc_md10"></a>
Method Mapping</h2>
<p>IDL method calls are mapped to JSON-RPC as follows:</p>
<p>In JSON-RPC Request:</p>
<ul>
<li>method name: element 'method' of request object</li>
<li>in-parameters: element 'params' of request object, containing an object with one element per parameter</li>
<li>out-parameters: not mapped</li>
<li>return value: not mapped</li>
</ul>
<p>Example (net.Net.setNetworkConfigLan): </p><div class="fragment"><div class="line">{</div>
<div class="line"> "jsonrpc": "2.0",</div>
<div class="line"> "method": "setNetworkConfigLan",</div>
<div class="line"> "params": {</div>
<div class="line"> "speed": 2,</div>
<div class="line"> "duplex": 0,</div>
<div class="line"> },</div>
<div class="line"> "id": 123</div>
<div class="line">}</div>
</div><!-- fragment --><p>In JSON-RPC Response:</p>
<ul>
<li>method name: not mapped</li>
<li>in-parameters: not mapped</li>
<li>out-parameters: element 'result' of response object, containing an object with one element per parameter</li>
<li>return value: special element'<em>ret</em>' of element 'result' of response object</li>
<li>system errors or exceptions: element 'error' of response object</li>
</ul>
<p>Example (result from <a class="el" href="interfacedevsettings_1_1Snmp.html#a5560fe7436455a475c28ecc9a9dca594" title="Retrieve the SNMP agent configuration.">devsettings.Snmp.getConfiguration</a>): </p><div class="fragment"><div class="line">{</div>
<div class="line"> "jsonrpc": "2.0",</div>
<div class="line"> "result": {</div>
<div class="line"> "v2enable": true,</div>
<div class="line"> "v3enable": false,</div>
<div class="line"> "readComm": "public",</div>
<div class="line"> "writeComm": "",</div>
<div class="line"> "sysContact": "",</div>
<div class="line"> "sysName": "",</div>
<div class="line"> "sysLocation": ""</div>
<div class="line"> },</div>
<div class="line"> "id": 456</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md11"></a>
Call Execution</h1>
<p>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.</p>
<p>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 <a class="el" href="well_known_rids.html">Well-Known Resource IDs</a>.</p>
<p>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.</p>
<h1><a class="anchor" id="autotoc_md12"></a>
Authentication</h1>
<p>All RPC calls must be authenticated with valid user credentials. Xerus™ supports two methods for passing those credentials:</p>
<ul>
<li>HTTP Basic Authentication</li>
<li>Raritan RPC Session Authentication</li>
</ul>
<h2><a class="anchor" id="autotoc_md13"></a>
Basic Authentication</h2>
<p>For HTTP basic authentication the user name and password must be included in the <code>Authorization</code> header of every HTTP request. The contents of the header line must be the keyword <code>Basic</code> followed by a base64-encoded string containing the user name and password, separated by a colon. For instance, to authenticate a request with the default login admin/raritan the following header must be sent:</p>
<div class="fragment"><div class="line">Authorization: Basic YWRtaW46cmFyaXRhbg==</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md14"></a>
Session Authentication</h2>
<p>For Session-based authentication the client contacts the session manager at <code>/session</code> to open a new session. The initial <code>newSession</code> 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 <code>X-SessionToken</code> HTTP header with the secret session token:</p>
<div class="fragment"><div class="line">X-SessionToken: 9e520dc84533342cd034b49550969e7f</div>
</div><!-- fragment --><p>The session token remains valid until the session expires or is closed. A session expires 30 seconds after the last request.</p>
<ul>
<li>see: session.SessionManager_2_0_0</li>
</ul>
<h1><a class="anchor" id="autotoc_md15"></a>
Bulk RPC</h1>
<p>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 <code>/bulk</code>.</p>
<p>A bulk request is performed by calling the performBulk method with a vector of resource IDs and JSON-RPC request objectss. The method returns a list of HTTP status codes and JSON-RPC response objects.</p>
<p>Example (sent to <a href="https://my-device/bulk">https://my-device/bulk</a>): </p><div class="fragment"><div class="line">{</div>
<div class="line"> "jsonrpc": "2.0",</div>
<div class="line"> "method": "performBulk",</div>
<div class="line"> "params": {</div>
<div class="line"> "requests": [</div>
<div class="line"> // First request: Firmware::getVersion()</div>
<div class="line"> { "rid": "/firmware",</div>
<div class="line"> "json": { "jsonrpc": "2.0", "method": "getVersion", "params": {}, "id": 1 } },</div>
<div class="line"> // Second request: EventLog::clear()</div>
<div class="line"> { "rid": "/eventlog",</div>
<div class="line"> "json": { "jsonrpc": "2.0", "method": "clear", "params": {}, "id": 2 } }</div>
<div class="line"> ]</div>
<div class="line"> },</div>
<div class="line"> "id": 123</div>
<div class="line">}</div>
</div><!-- fragment --><p>Response: </p><div class="fragment"><div class="line">{</div>
<div class="line"> "jsonrpc": "2.0",</div>
<div class="line"> "result": {</div>
<div class="line"> "responses": [</div>
<div class="line"> // First response: HTTP 200 (OK), firmware version</div>
<div class="line"> { "statcode": 200,</div>
<div class="line"> "json": { "jsonrpc": "2.0", "result": { "_ret_": "3.1.0.5-23456" }, "id": 1 } },</div>
<div class="line"> // Second response: HTTP 200 (OK), no return value</div>
<div class="line"> { "statcode": 200,</div>
<div class="line"> "json": { "jsonrpc": "2.0", "result": null, "id": 2 } }</div>
<div class="line"> ]</div>
<div class="line"> },</div>
<div class="line"> "id": 123</div>
<div class="line">}</div>
</div><!-- fragment --><p>The Java language binding uses bulk RPC by default when using the asynchronous API. The Perl und Python bindings do not support bulk RPC yet.</p>
<ul>
<li>see: bulkrpc.BulkRequest_1_0_1 </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Mon Oct 17 2022 00:25:43 for Raritan / Server Technology Xerus™ PDU JSON-RPC API by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
|
