As a user of Client Accelerator Controller, formerly known as SteelCentral Controller for SteelHead Mobile, you may be asked to automate workflows such as generating custom endpoint usage reports, configuring policies, and performing cluster 
maintenance. The Client Accelerator Controller provides a REST-based Application Programming Interface so that you can develop these types of automation tools and integrate the Controller with your other systems.
In part one of this series, you learned how to enable the REST API in the Controller, create an access code, and use that access code to generate an OAuth bearer token. This article will teach you how to find specific REST API command documentation online and use the bearer token in a sample Python script that will generate a report of User endpoints, similar to the output found on the Controller web UI shown.
Online REST API Documentation
You can find all Riverbed API details online. For the Client Access Controller APIs, select the item shown.
The subsequent webpage will bring you to the online REST API specification documents. There is a drop-down at the upper-right that you use to select an aspect of the API you want to learn more about. For the use case of generating User endpoint reports, you would select the Statistics option, as shown.
A short-cut to this page is provided here.
There are three important areas on this page. The first item, located at the upper-left, is a link that will provide you the API Swagger/OpenAPI specification. This YAML formatted file is very informative as it provides the exact details for each API definition. There are open-source tools that can consume this file and even auto-generate Python client code (see References section).
The second item, highlighted in yellow, indicates the API prefix value that you would add to your Controller base URL. For example, if your Controller base URL were https://my-client-accellerator.mycorp.com, then the URL for all APIs documented on this page would be https://my-client-accellerator.mycorp.com/api/stats/1.0.0.
The third item is the collection of API routes that provide you specific controls. The first API in this collection is /report/endpoints. If you click on that area of the webpage, you will see more documentation about this API. The complete URL to access this API would be the base URL plus the Statistics prefix plus the specific route. For this first /report/endpoints API, the complete URL would be https://my-client-accellerator.mycorp.com/api/stats/1.0.0/report/endpoints.
The expanded /report/endpoint API definition is shown. A short-cut to this page is here.
Python Example Script to Create Endpoint Report
This next section presumes you are familiar with Python and installing packages from the PyPi repository system. A tutorial can be found here.
Now that you have a bearer token, you can use it to access the REST API. As an example use case, we will execute the API to retrieve the Report for Endpoints. This API call will provide you the same information as you would find in the Controller web UI here shown.
Before you attempt to use this example code, you will need to set up a virtual environment and install the httpx and tabulate packages. Please review the function login described in part one of this series. The login function is used to create a REST client instance and re-used in this report example. Recall that the login function retrieves the Controller Access Code from a file called access-code.txt; in a production environment, you would typically retrieve this from a secure system.
Starting on line 26, the function get_endpoints invokes the REST GET request on the API /report/endpoints. The API parameter is the Controller client instance created as a result of calling the login function on line 33.
Line 28 checks the REST response and raises an exception if there is an error. For example, if the API token has expired (would not be the case for a short script like this example), the HTTP status code would be 401, and the exception would be as shown.
When the response contains a valid payload of data, the response status_code will be 200. Line 29 extracts the response body as a JSON payload as the API specification defined this to be the case. Line 30 returns the endpoint records from the data portion of the payload.
The payload, as a Python dictionary, contains two keys: meta and data. The purpose of the meta values is to provide information about the data response, for example, the total number of records available and the total number of records provided in the response body. This metadata is very useful when you need to understand how many records exist and if you need to execute many GET requests to get the page data results versus getting all of the records at once. The following shows the metadata for a Controller that has four endpoints.
If you look back at the API specification for /report/endpoints, you will find that the GET API allows for two paging parameters called limit and offset.
You can see the limit default is 20, and this is why you find the value 20 in the metadata portion of the response body.
Each endpoint record is an item in the data list. Examining the first record, we will find a dictionary of values.
We can see that this endpoint user is achieving a total reduction of 42.69 percent from the response data. Looking back at the Controller web UI snapshot, you will find that this matches.
Using these records, you can create a tabular report as illustrated by the new code example. Note that two new imports are listed at the top of the file. The itemgetter function is used to extract the specific fields from the data records. The tabulate function creates a pretty table output.
Line 38 uses the itemgetter function to extract only the record fields displayed in the tabular output. Starting at line 40, the print function calls tabulate to create a text-table and prints the result. This code produces the output:
If you wanted to sort this table using the Total Reduction value, the new code would be as shown.
The new code is on line 39. This line is used to sort the table_data using the value located in position 1 of the table record; position 1 corresponds to the ‘total_red’ field. The sorted parameter reverse = True is used to sort the table from highest value to lowest value. The resulting table output is as shown.
Summary
This article provided the information to get started using the Client Accelerator Controller API with a focus on using the statistics portion of the REST API. Key highlights about the Controller API:
- REST-based API
- Uses OAuth and Bear Token authentication approach
- OAuth token is valid for one (1) hour only
- Online documentation is available directly from the Controller web UI
- Swagger/OpenAPI files are available
- Response payload includes metadata
- API supports paging for large sets of records
This article also provided short examples demonstrating how to use the API to retrieve the User endpoint records and present a concise tabular report.
If you are interested in exploring existing open-source software libraries and examples, you can find the Riverbed open-source Github organization of repositories: https://github.com/riverbed
References:
