HomeGuidesAPI Reference
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In
GuidesAPI ReferenceGitHubAirheads Developer Community

Using Python REST API SDK

PyPi Package

Suggest Edits

Aruba Central is an unified cloud-based network management and configuration platform for campus, branch, remote and data center networks. There are various needs for automation and programmability like automating repetitive tasks, configuring multiple devices, monitoring and more. This python package is to programmatically interact with Aruba Central via REST APIs.

How to Install?

Install using Python package manager 

pip3 install pycentral

To install with extras, which displays log messages in color, install package with the following command 

pip3 install pycentral[colorLog]

Package structure

The dir structure of the pycentral package is as follows. 

│   README.md
│   Contributions.md
│   ...
│
└───pycentral
│   │   base.py
│   │   configuration.py
│   │   ...
│   │
│   └───workflows
│       │   config_apsettings_from_csv.py
│       │   ...
│
└───docs
    │   ...

pycentral

The pycentral subfolder contains the Aruba Central Python modules. Each module contains multiple Python classes. Each Class is a representation of some of the Aruba Central's API categories as mentioned in the API Reference section. Each class has its own function definitions that are used to make a single REST API call.

In addition to using the modules provided by the package, there is also a module base.py containing function ArubaCentralBase.command(). This function can make any REST API call using the API endpoint URL, HTTP Method, HTTP query params and HTTP payload as required by an API endpoint. The REST API calls are made using the Python requests library by ArubaCentralBase.command(), as supported by Aruba Central API Gateway endpoints.

📘

Module Documentation

To get list of implemented modules and its documentation visit python module documentation.

Gathering requirements

Gathering variables required for the package base class ArubaCentralBase.

  • base_url

You can find the base URL of the Central account's API Gateway from the table here. The base URL is based on the geographical Central cluster in which the account is registered.

  • client_id and client_secret

Obtain client_id and client_secret variables by creating an API Gateway client in Aruba Central. Refer the Aruba API Gateway section for more details.

Obtain the customer_id by clicking on the figure icon on top right corner of Aruba Central WebUI.

  • username and password
    Aruba Central user's username and password. The access token generated by the OAUTH APIs will have the same role/privileges as the provided Aruba Central user credentials.

Execution

ArubaCentralBase class requirements

ArubaCentralBase class requires one mandatory argument central_info. Other optional arguments are token_store and ssl_verify.

1. central_info
One of the following options can be used.

a. Either Provide variables obtained from Gather Requirements section directly to Aruba Central Base class in Python dict structure.

central_info = {
    "base_url": "<api-gateway-domain-url>",
    "token": {
        "access_token": "<api-gateway-access-token>"
    }
}

central_info = {
   "username": "<aruba-central-account-username>",
   "password": "<aruba-central-account-password>",
   "client_id": "<api-gateway-client-id>",
   "client_secret": "<api-gateway-client-secret>",
   "customer_id": "<aruba-central-customer-id>",
   "base_url": "<api-gateway-domain-url>"
}

b. OR Provide the required variables using JSON/YAML file. Use pycentral.workflows_utils.get_conn_from_file() function which accepts name of the file and returns the ArubaCentralBase instance object. YAML examples are provided below.

central_info:
  base_url: "<api-gateway-domain-url>"
  token:
    access_token: "<api-gateway-access-token>"
ssl_verify: true

central_info:
  username: "<aruba-central-account-username>"
  password: "<aruba-central-account-password>"
  client_id: "<api-gateway-client-id>"
  client_secret: "<api-gateway-client-secret>"
  customer_id: "<aruba-central-customer-id>"
  base_url: "<api-gateway-domain-url>"
token_store:
  type: "local"
  path: "temp"
ssl_verify: true

2. token_store
As provided in the above YAML file, token_store default settings are type "local" and path "temp". When OAUTH APIs approach is used, a new access token will generated and cached in the mentioned path of local python host machine. This assists in access_token re-use and help in refreshing expired tokens by the package instead of creating a new access_token.

3. ssl_verify
This argument is of boolean type and default setting is "true". When set to "true", the python client will validate Aruba Central's SSL certs while making HTTPS requests.

❗️

Security Note

  • File accepted by pycentral.workflows_utils.get_conn_from_file() are not encrypted. Implement your preferred security encryption method for added security.

  • In addition, by taking OAUTH APIs approach the pycentral package will cache generated access_token in local machine in unencrypted JSON file. Override ArubaCentralBase.storeToken() and ArubaCentralBase.loadToken() by leveraging the ArubaCentralBase.token_store variable to implement your own secure token storage mechanism.


Sample scripts

  1. Making API call using pycentral base
    Using the base class ArubaCentralBase, any Aruba Central supported REST API calls can be made. A list of groups from Aruba Central can be obtained from the script below. Obtain the HTTP Path, HTTP Method and HTTP query params from Aruba Central Swagger documentation or API references section.

Execute the script ,after filling central_info variable, with command python3 pycentral_base_sample.py.

from pycentral.base import ArubaCentralBase
from pprint import pprint

# Create an instance of ArubaCentralBase using API access token 
# or API Gateway credentials.
central_info = {
    "base_url": "<api-gateway-domain-url>",
    "token": {
        "access_token": "<api-gateway-access-token>"
    }
}
ssl_verify = True
central = ArubaCentralBase(central_info=central_info,
                           ssl_verify=ssl_verify)

# Sample API call using 'ArubaCentralBase.command()'
# GET groups from Aruba Central
apiPath = "/configuration/v2/groups"
apiMethod = "GET"
apiParams = {
    "limit": 20,
    "offset": 0
}
base_resp = central.command(apiMethod=apiMethod, 
                            apiPath=apiPath,
                            apiParams=apiParams)
pprint(base_resp)

🚧

Security Note

Please Note that you would not want to hardcode access_token directly in a production script.

  1. Making API call using pycentral modules
    Some API endpoints supported by Aruba Central are implemented as modules in the Python package. pycentral.configuration module and Groups class is used below to obtain list of groups from Aruba Central.

Execute the script, after filling central_info variable, with command python3 pycentral_module_sample.py.

# Import Aruba Central Base
from pycentral.base import ArubaCentralBase
from pprint import pprint

# Create an instance of ArubaCentralBase using API access token 
# or API Gateway credentials.
central_info = {
    "base_url": "<api-gateway-domain-url>",
    "token": {
        "access_token": "<api-gateway-access-token>"
    }
}
ssl_verify = True
central = ArubaCentralBase(central_info=central_info, 
                           token_store=None, 
                           ssl_verify=ssl_verify)

# Sample API call using Configuration sub-module `pycentral.configuration`
from pycentral.configuration import Groups

# Get groups max limit 20, apply offset and fetch other groups in loop
g = Groups()

module_resp = g.get_groups(central)
pprint(module_resp)

Workflows

Workflows are used to achieve an automation use-case which generally involves multiple API calls or dealing with scale and repetitive tasks with ease. Check out the central-python-workflowsrepository to check out workflows that utilize the Pycentral library.

Updated 9 months ago

What’s Next