This article discusses how to use Stingray's RESTful Control API with TrafficScript, Stingray's scripting language. The RESTful API can be accessed in a TrafficScript rule using the http.request.get(), http.request.put() and http.request.delete() functions, but to make programming easier I have taken advantage of the support in TrafficScript for subroutine libraries to create a TrafficScript REST client that contains subroutines that be can be used by TrafficScript rules and that abstract many of the RESTful API programming details.
Resources
The RESTful API gives you access to the Stingray Configuration, presented in the form of resources. The format of the data exchanged using the Stingray RESTful API will depend on the type of resource being accessed:
- Data for Configuration Resources, such as Virtual Servers and Pools are exchanged in JSON format using the MIME type “application/json”, so when getting data on a resource with a GET request the data will be returned in JSON format and must be deserialized or decoded into a TrafficScript data structure. When adding or changing a resource with a PUT request the data must be serialized or encoded from a TrafficScript data structure into JSON format.
- Files, such as rules and those in the extra directory are exchanged in raw format using the MIME type “application/octet-stream”.
Working with JSON and TrafficScript
TrafficScript provides functions for JSON serializing and deserializing. To take a TrafficScript data structure and serialize it into JSON format, use json.serialize() and to deserialize a JSON formatted string into a TrafficScript structure, use json.deserialize().
Working with the RESTful API and TrafficScript
To make the programming easier, the program examples that follow utilize the stmrestclient REST client. To use stmrestclient in a TrafficScript rule you include it with the import statement:
import stmrestclient;
The hostname of the STM to access, the base URI path and the userid and password are defined in stmrestclient and can be changed there if needed. The default is for the hostname to be the same as the STM on which the rule is running and the userid and password are both "admin". There are three subroutines for use in rules:
stmRestGet(resourcepath, type)
stmRestPut(resourcepath, type, data)
stmRestDelete(resourcepath)
resourcepath identifies the part of the URI path to the resource that needs to be added to the base URI path. The base URI path is "/api/tm/1.0/config/active/". So for example, to get a list of pools, resourcepath would be set to "pools" or to work with the pool "testpool", resourcepath would be set to "pools/testpool", resulting in a URI path of "/api/tm/1.0/config/active/pools" and "/api/tm/1.0/config/active/pools/testpool" respectively.
type identifies the format of the data and should be set to "json", "file" or "any". These will be translated to “application/json”, “application/octet-stream” and “application/json, application/octet-stream” respectively.
data should be a TrafficScript hash for configurations resources or a string for files.
Each subroutine returns the following hash:
- rc: Return code. 1=OK, 0=Error
- info: "OK" if OK, and an error message if there was an error
- data: The data from the response. A hash containing one element, "children" for lists or "properties" for configuration data. For files it is the file.
- content-type: The Content-Type header of the response, either “application/json” or “application/octet-stream”
- status: The HTTP response code
Data Structures
Responses that return a JSON formatted string will be deseriailized by the stmrestclient subroutines into a hash that always contains one element. The key to this element will be:
- "children" for lists of resources. The value will be an array with each element in the array being a hash with the key, "name", set to the name of the resource and the key, "href", set to the URI of the resource.
- "properties" for configuration resources. The value will be a hash with each key value pair being a section of properties with the key being set to the name of the section and the value being a hash containing the configuration values as key/value pairs. Configuration values can be scalars, arrays or hashes.
Please see Feature Brief: Traffic Manager's RESTful Control API for examples of these data structures and tools such as the Chrome REST Console can be used to see what the actual data looks like.
Example
The following rule will get a list of all pools and create a webpage listing them:
import stmrestclient;
$html = "Pools:
\n";
$response = stmrestclient.stmRestclient("pools", "json");
if ($response["rc"]) {
$pools = $response["data"]["children"];
foreach ($pool in $pools) {
$html = $html . $pool["name"] . "
";
}
} else {
$html = $html . "There was an error getting the pool list: " . $response['info'];
}
http.sendResponse("200 OK", "text/html", $html, "");
stmrestclient
The TrafficScript code for the STM REST client, stmrestclient, has been attached to this article.
Read More
