Using Python REST API SDK

HPE Aruba Networking Central is a 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 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 Central Python modules. Each module contains multiple Python classes. Each Class is a representation of some Central 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 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.

• access_token: You can create an API access token for Central from -

  • Central UI
  • OAuth APIs

• customer_id

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

• username and password
  Central user's username and password. The access token generated by the OAUTH APIs will have the same role/privileges as the provided 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 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 Central supported REST API calls can be made. A list of groups from Central can be obtained from the script below. Obtain the HTTP Path, HTTP Method and HTTP query params from 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.

2. Making API call using pycentral modules
   Some API endpoints supported by Central are implemented as modules in the Python package. pycentral.configuration module and Groups class is used below to obtain list of groups from 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-workflows repository to check out workflows that utilize the Pycentral library.