Tech Tip: Using the RESTful Control API with Python - Overview

[#1]

This article explains how to use Stingray's REST Control API using the excellent requests Python library.

There are many ways to install the requests library.  On my test client (MacOSX), the following was sufficient:

$ sudo easy_install pip

$ sudo pip install requests

Resources

The REST 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 of “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 Python data structure.  When adding or changing a resource with a PUT request the data must be serialized or encoded from a Phython data structure into JSON format.
• Files, such as rules and those in the extra directory are exchanged in raw format using the MIME type of “application/octet-stream”.

Working with JSON and Python

The json module provides functions for JSON serializing and deserializing.  To take a Python data structure and serialize it into JSON format use json.dumps() and to deserialize a JSON formatted string into a Python data structure use json.loads().

Working with a RESTful API and Python

To make the programming easier, the program examples that follow utilize the requests library as the REST client. To use the requests library you first setup a requests session as follows, replacing <userid> and <password> with the appropriate values:

client = requests.Session()
client.auth = ('<userid>', '<password>')
client.verify = False

The last line prevents it from verifying that the certificate used by Stingray is from a certificate authority so that the self-signed certificate used by Stingray will be allowed.  Once the session is setup, you can make GET, PUT and DELETE calls as follows:

response = client.get()
response = client.put(, data = , headers = )
response = client.delete()

The URL for Stingray RESTful API will be of the form:

https://<STM hostname or IP>:9070/api/tm/1.0/config/active/

followed by a resource type or a resource type and resource, so for example to get a list of all the pools from the Stingray instance, stingray.example.com, it would be:

https://stingray.example.com:9070/api/tm/1.0/config/active/pools

And to get the configuration information for the pool, “testpool” the URL would be:

https://stingray.example.com:9070/api/tm/1.0/config/active/pools/testpool

For most Python environments, it will probably be necessary to install the requests library.  For some Python environments it may also be necessary to install the httplib2 module.

Data Structures

JSON responses from a GET or PUT are deserialized into a Python dictionary that always contains one element.   The key to this element will be:

• 'children' for lists of resources.  The value will be a Python list with each element in the list being a dictionary 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 dictionary 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 dictionary containing the configuration values as key/value pairs.  Configuration values can be scalars, lists or dictionaries.

Please see Feature Brief: Stingray's RESTful Control API for examples of these data structures and something like the Chrome REST Console can be used to see what the actual data looks like.

Read More

• The REST API Guide in the Stingray Product Documentation
• Feature Brief: Stingray's RESTful Control API
• Collected Tech Tips: Using the RESTful Control API