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

[#1]

This article explains how to use Stingray's REST Control API using the excellent rest-client Ruby module.

You can install rest-client with gem:

Windows: gem install rest-client
Linux: sudo gem install rest-client

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 Ruby data structure.  When adding or changing a resource with a PUT request the data must be serialized or encoded from a Ruby 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 Ruby

The json module provides functions for JSON serializing and deserializing.  If this is not already installed on your system it can be installed with gem:

Windows: gem install json
Linux: sudo gem install json

To take a Ruby data structure and serialize it into JSON format use JSON.generate() and to deserialize a JSON formatted string into a Ruby data structure use JSON.parse().

Working with a RESTful API and Ruby

To make the programming easier, the program examples that follow utilize the rest-client package as the REST client. There are methods for GET, PUT and DELETE and each must include an authorization header, replacing <userid>, <password>, <url> and <data> with the appropriate values:

auth = 'Basic ' + Base64.encode64('<useid>:<password>')
response = RestClient.get(<url>, {:authorization => auth})
response = RestClient.put(<url>, JSON.generate(<data>), {:content_type => :json, :authorization => auth})
response = RestClient.delete(<url>, {:authorization => auth})

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

Data Structures

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

• 'children' for lists of resources.  The value will be a Ruby array with each element in the array 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 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 or arrays or hashes.

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