Beside the basic I/O functions described in the previous chapters, the sat-nms driver definition language provides some statements to handle the communication with devices using a REST API in an efficient way.
The REST API transports settings and status information as structured, JSON-formatted documents over an HTTP protocol. JSON documents are plain text and therefore may be - at least principally - handled by the basic PRINT / INPUT statements. In practice however, parsing a JSON document with the capabilities of INPUT may become difficult and in the end will result in a device driver which is hard to understand and to maintain.
The REST I/O statements contained in the sat-nms driver definition language take care of the special structure and formatting of JSON documents, helping to focus on the content to send or retrieve rather than the special JSON syntax. The statements for REST communication are:
| REST TRANSACT | Sends a REST HTTP request to the device, for HTTP POST, PUT or PATCH with a JSON formatted document body attached. Retrieves the device's reply and parses the document body into an object tree. |
| REST PARSE | Accesses the objects contained in the most recent reply from the device and assigns the object values to sat-nms driver variables. |
| REST SET | Modifies the objects contained in the JSON document or adds new objects to it. Used to prepare a document to be sent to the device with one of the POST, PUT or PATCH HTTP methods. |
| REST CLEAR | Clears the JSON document in memory. This function is used to prepare a document from scratch for a POST or PATCH call. |
| REST SEND | takes the actual JSON document and sends it to the device. It is used with protocols other than HTTP and replaces REST TRANSACT there. |
Object model
A JSON document is a hierarchically structured collection of key / value pairs. The value in such a pair may be either a constant value, another ancillary collection or an array of these. The object model used in the sat-nms REST I/O functions flatens this tree-like structure, treats every constant value with its key as an object. The key of this constant value is extended to contain the complete information where in the document this key / value pair is located.
Object paths
This location information can be thought as a path from the document's root down to the definition of the constant value of interest. This path is much like a path in a computer's file system. The higher-order nodes in the document tree are like directories in the file system. For this reason, the sat-nms driver definition language uses a notation like used with file names to identify an object in the document tree:
/settings/modulator/dataratefor example denotes an object datarate contained in the modulator branch of the document which in turn is expected to be contained in the settings branch. The JSON equivalent of this would look like this:
{
"settings": {
"modulator": {
"datarate": 2048000;
};
};
}As with file names and paths, a path identifying an object may be absolute or relative. The example above uses an absolute path to the object: it starts with a slash character. When you access /settings/modulator/datarate, the software makes an implicit change directory to /settings/modulator. If you access then an object named for example fec, the software automatically will expand the object name to /settings/modulator/fec. This works inside a single REST SET or REST PARSE statement, not across separate statements.
Object arrays
The array construct in a JSON document works in a special way and therefore needs some special treatment in the sat-nms driver definition language. JSON arrays are a collection of equally structured nodes. In most REST APIs, the elements of such a collection are not identified by their location in in the collection but by some unique identifier which appears as a regular key / value pair in each element of the array.
To cope with this construct, the sat-nms driver definition language exteds the object path definition with "conditions" used to identify a particular collection element:
/settings/modulator/output[id=3]/enableaddresses the enable object in that output branch that has a key id set to 3. Conditions may appear after each branch name in the object path. There may be multiple conditions which are combined with a logical and:
/settings/modulator/connector[number=2][type=OUTPUT]/enableaddresses the enable object in that connector branch that has a key number set to 3 and type set to OUTPUT.
Alternatively, array elements may be addressed by their position in the array. The numeric array index starts with 0 for the first array element:
/settings/modulator/output[2]/enableaddresses the enable object in the third (index=2) 'output' branch. Please note, that this only works, if the API of the device to control explicitly permits to access array elements by position. Furthermore it is not possible to create array elements by position index in the REST SET statement.
Document handling
With the REST statements in the sat-nms driver definition language there is always one JSON document in memory these statements work on. Generally, it is the REST TRANSACT statement which creates this document from the device's reply, REST CLEAR creates an empty document instead. The REST SET statement can be used to add or modify objects in the document, the REST PARSE statement to query objects from there.
With a REST TRANSACT doing a HTTP GET command you can expect to get the information you addressed in the GET command, but POST, PUT or PATCH also may return a document containing some information that might be important for the device driver.
When issuing a POST, PUT or PATCH command, the REST TRANSACT statement sends the existing document to the device using the selected HTTP method, then replaces the document by the parsed reply from the device.