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

[#1]

This article discusses how to use the Stingray Traffic Manager's RESTful Control API with PHP.  The are different options for accessing the RESTful API with PHP, but I decided to create my own PHP REST Client, STMRESTClient, to make working with RESTful API easier, and this has been used in the PHP examples. Instructions for using STMRESTClient and the code can be found here: Tech Tip: A Stingray Traffic Manager REST Client for PHP

Resources

The RESTful API gives you access to the Stingray Configuration and statistics, 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 ans Status Resources, such as Virtual Servers and Pools are exchanged in JSON format using the MIME type “application/json”, so when getting data for a resource with a GET request, the data will be returned in JSON format and must be deserialized or decoded into a PHP data structure.  When adding or changing a resource with a PUT request, the data must be serialized or encoded from a PHP 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 PHP

PHP provides functions for JSON encoding and decoding. To take a PHP data structure and encode it into JSON format, use json_encode() and to decode a JSON formatted string into a PHP structure, use json_decode(). If using STMRestClient, JSON encoding and decoding will be done for you.

Working with the RESTful API and PHP

The base form of the URI for the Stingray RESTful API is:

https://<host>:<port>/api/tm/<version>

followed by paths to the different resource types:

• For configuration resources: /config/active/
• For statistic resources: /status/<host>/information/
  "local_tm" can be used in place of <host>
• For information resources: /status/<host>/statistics/

"local_tm" can be used in place of <host>

followed by a actual 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/2.0/config/active/pools

and to get the configuration information for the pool, “testpool” it would be:

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

and to get statistics for the pool "testpool", it would be:

https://stingray.example.com:9070/api/tm/2.0/status/local_tm/statistics/pools/testpool

Prerequisites

If your PHP environment does not have cURL installed, you will need to install it, even if you are using STMRestClient.

If using apt (assuming apache is the web server):

sudo apt-get install php5-curl

sudo service apache2 restart

Data Structures

The PHP functions json_decode and json_encode convert between JSON strings and PHP data structures.  The PHP data structure can be either an associative array or an object.  In either case, the array or object will have one element.   The key to this element will be:

• 'children' for lists of configuration resources.  The value will be a PHP array with each element in the array being an associative array 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 an associative array 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 an associative array containing the configuration values as key/value pairs.  Configuration values can be scalars, arrays or associative arrays.
• 'statistics' for statistics resources.  The value will be an associative array.
• 'information' for information resources.  The value will be an associative array.

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
• Tech Tip: A Stingray Traffic Manager REST Client for PHP