vADC Docs

Feature Brief: Stingray's RESTful Control API

by ricknelson on ‎02-27-2013 09:42 AM - edited on ‎07-14-2015 04:31 PM by PaulWallace (5,781 Views)

Overview

 

Stingray's RESTful Control API allows HTTP clients to access and modify Stingray cluster configuration data.  For example a program using standard HTTP methods can create or modify virtual servers and pools, or work with other Stingray configuration objects.

 

The RESTful Control API can be used by any programming language and application environment that supports HTTP.

 

Resources

 

The Stingray RESTful API is an HTTP based and published on port :9070.  Requests are made as standard HTTP requests, using the GET, PUT or DELETE methods.  Every RESTful call deals with a “resource”.  A resource can be one of the following:

 

  • A list of resources, for example, a list of Virtual Servers or Pools.
  • A configuration resource, for example a specific Virtual Server or Pool.
  • A file, for example a rule or a file from the extra directory.

 

Resources are referenced through a URI with a common directory structure.  For this first version of the Stingray RESTful API the URI for all resources starts with “/api/tm/1.0/config/active”, so for example to get a list of pools, the URI would be “/api/tm/1.0/config/active/pools” and to reference the pool named “testpool”, the URI would be “/api/tm/1.0/config/active/pools/testpool.

 

When accessing the RESTful API from a remote machine, HTTPS must be used, but when accessing the RESTful API from a local Stingray instance, HTTP can be used.

 

By default, the RESTful API is disabled and when enabled listens on port 9070.  The RESTful API can be enabled and the port can be changed in the Stingray GUI by going to System->Security->REST API.

 

To complete the example, to reference the pool named “testpool” on the Stingray instance with a host name of “stingray.example.com”, the full URI would be “https://stingray.example.com:9070/api/tm/1.0/config/active/pools/testpool”.  To get a list off all the types of resources available you can access the URL,  “https://stingray.example.com:9070/api/tm/1.0/config/active".

 

To retrieve the data for a resource you use the GET method, to add or change a resource you use the PUT method and to delete a resource you use the DELETE method.

 

Data Format

 

Data for resource lists and configuration resources are returned as JSON structures with a MIME type of "application/json".  JSON allows complex data structures to be represented as strings that can be easily passed in HTTP requests.  When the resource is a file, the data is passed in its raw format with a MIME type of "application/octet-stream".

 

For lists of resources the data returned will have the format:

 

{

     "children": [{

          "name": "",

          "href": "/api/tm/1.0/config/active/pools/"

     }, {

          "name": "",

          "href": "/api/tm/1.0/config/active/pools/"

     }]

}

 

For example, the list of pools, given two pools, “pool1” and “pool2” would be:

 

{

     "children": [{

          "name": "pool1",

          "href": "/api/tm/1.0/config/active/pools/pool1"

     }, {

     "children": [{

          "name": "pool2",

          "href": "/api/tm/1.0/config/active/pools/pool2"

     }]

}

 

For configuration resources, the data will contain one or more sections of properties, always with at least one section named "basic", and the property values can be of different types.  The format looks like:

 

{
     "properties": {

          "<section name>": {

               "<property name>": "<string value>",

               "<property name>": <numeric value>,

               "<property name>": <boolean value>,

               "<property name>": [<value>, <value>],

               "<property name>": [<key>: <value>, <key>: <value>]

     },

          "<section name>": {

               "<property name>": "<string value>",

               "<property name>": <numeric value>"
     }

 

Accessing the RESTful API

 

Any client or program that can handle HTTP requests can be used to access the RESTful API. Basic authentication is used with the usernames and passwords matching those used to administer Stingray.  To view the data returned by the RESTful API without having to do any programming, there are browser plug-ins that can be used.  One that is available, is the Chrome REST Console.  It is very helpful during testing to have something like this available.  One nice thing about a REST API is that it is discoverable, so using something like the Chrome REST Console, you can walk the resource tree and see everything that is available via the RESTful API.  You can also add, change and delete data.  For more information on using the Chrome REST Console see: Tech Tip: Using Stingray's RESTful Control API with the Chrome REST Console

 

When adding or changing data, use the PUT method and for configuration resources, the data sent in the request must be in JSON format and must match the data format returned when doing a GET on the same type of resource.  For adding a configuration resource you do not need to include all properties, just the minimum sections and properties required to add the resource and this will vary for each resource.  When changing data you only need to include the sections and properties that need to be changed.  To delete a resource use the DELETE method.

 

Notes

 

  • An important caution when changing or deleting data is that this version of the RESTful API does do data integrity checking.  The RESTful API will allow you to makes changes that would not be allowed in the GUI or CLI.  For example, you can delete a Pool that is being used by a Virtual Server.  This means that when using the RESTful API, you should be sure to understand the data integrity requirements for the resources that you are changing or deleting and put validation in any programs you write.
  • This release of the RESTful API is not compatible with Multi-Site Manager, so both cannot be enabled at the same time.

 

Read more

 

Contributors