Getting Started with the AFC API

Introduction

The AFC API utilizes the REpresentational State Transfer (abbreviated as REST) architecture and standards as an automation vehicle of interaction. As an open standard, REST makes it easy for AFC automation to be supported by several different programming languages and frameworks.

📘

What is an API?

An Application Programming Interface (API) is a set of routines, protocols, and tools to define interactions between software applications.

Accessing the AFC API Explorer UI

The Aruba Fabric Composer has a built-in Web UI for the REST API. This can be reached by logging into the AFC Web UI, then clicking the ? in the top right, and selecting API Explorer.

API Authentication

To start using the AFC API, users will first need to obtain an API token for authorization. This involves a POST method to the /auth/token/ resource with the credentials in the header, and retrieving the token for further API calls. An example POST header to an AFC instance with an IP address of 172.168.0.1 using the default credentials for a brand new AFC install would be:

POST "https://172.168.0.1/api/v1/auth/token" -H "X-Auth-Username: admin" -H "X-Auth-Password: aruba" -H "Content-Type: application/json"

Example response body

{
  "result": "bde76581db5d67e6aefc22e29a863b52a3f3977c7c589cd55074e0904a71xcviuf222ea4d7d5bdd931909ac2osdf",
  "time": "716.516mS",
  "count": 1
}

The X-Auth-Username and X-Auth-Password are the required headers for this particular call, but there are also optional body parameters available as well. The key token-lifetime has a default integer value of 30 (minutes), and controls how many minutes the auth token is usable before it times out.
The optional header X-Auth-Refresh-Token is a boolean that can be added to any authenticated API call to automatically extend the token expiration for the calling user, when set to true.

Using the API Auth Key

The value for "result" from the response body will function as your API key, which has a valid lifetime based on the token-lifetime as mentioned above (default 30 minutes).

Further API calls must use that key with the Authorization Header going forward.
One such example would be:

GET "https://172.168.0.1/api/v1/api/vlan_groups" -H "Authorization: bde76581db5d67e6aefc22e29a863b52a3f3977c7c589cd55074e0904a71xcviuf222ea4d7d5bdd931909ac2osdf"

🚧

Max token Usage

A given user can have a max of 10 tokens in use at the same time. Additional token requests beyond that limit will cause older tokens (expired or not) to be deleted to allow new token provisioning.

Users can also explicitly delete their authentication token using a DELETE method on /auth/token/ with the Authorization Header and key specified.

DELETE "https://172.168.0.1/api/v1/auth/token" -H "Authorization: bde76581db5d67e6aefc22e29a863b52a3f3977c7c589cd55074e0904a71xcviuf222ea4d7d5bdd931909ac2osdf"