Overview

Welcome to Avi Vantage™ by Avi Networks, Inc. This manual covers Avi Vantage RESTful Application Programming Interface (API) guide.

HTTP Headers

Avi Controller REST APIs uses HTTP Headers and cookies for authentication, denoting content type, ordering, filtering, pagination, etc.

Request Headers

acf
Name Mandatory Description Usage
Content-Type Yes Content format. Should be application/json Content-Type: application/json
X-Avi-Version Yes API version to use for the API call. Avi controller supports all the API version which is less than equal to the version of the Controller. In order to use a feature that is released in a version, eg. 17.2.7, the API version should be greater than or equal to 17.2.7. It is important to remember that API version determines the version of the API data. As best practice, users once users have performed integration with a controller and API version then they should keep using it till they tested integration with the new API Version. X-Avi-Version: 18.1.2
X-Avi-Tenant No Tenant context. If not present, default tenant for user is used X-Avi-Tenant: acme
Authorization Yes Encoded Auth credentials in Base64 or authenticated sessionid cookie is mandatory Authorization: Basic yjfsdnj984498
X-CSRFToken Yes CSRF Token for POST/PUT. Use from csrftoken cookie X-CSRFToken: hdsbf84r34FFI39nvd398
Referer Yes NB: Mandatory for POST only Parent page Referer: http://10.10.10.10/
Accept-Encoding Yes NB: Mandatory for GET only Requested content format. Should be application/json Accept-Encoding: application/json

Response Headers

Name Description Format
Content-Type Content format. Should be application/json Content-Type: application/json

Response Cookies

Name Description Format
csrftoken Auth Token for session csrftoken: HF48348nvdvvdhh8
sessionid Session ID sessionid: fdsh734FG578b

Authentication

Avi Controller allows REST API usage using both Basic Authentication (over https) and Session Authentication.

Basic authentication

Auth credentials are encoded as Base 64 and sent as the Authorization header in every request. The following example retrieves the cluster version using basic authentication using the requests python library. resp = requests.get('https://10.10.1.101/api/cluster/version', verify=False, auth=('admin','adminpassword'))

Session authentication

The client performs a login to the controller. After authentication, a session is established and the sessionid is passed back to the client as a cookie. The client returns the sessionid cookie for subsequent requests. To end the session, the client performs a logout to the controller with the CSRFToken and controller IP in the headers. The following example retrieves the cluster version after session establishment, and then terminates the session. 


login = requests.post('https://10.10.1.101/login', verify=False, data={'username': 'admin', 'password': 'adminpassword'})
resp = requests.get('https://10.10.1.101/api/cluster/version', verify=False, cookies=dict(sessionid= login.cookies['sessionid']))
logout = requests.post('https://10.10.1.101/logout', verify=False, headers={'X-CSRFToken': login.cookies['csrftoken'], 'Referer':'https://10.10.1.101'}, cookies=login.cookies)

Object Tenancy

A tenant is associated with every object. 'admin' tenant is the default tenant that exists from the beginning.

Users can just access tenants where they have been assigned a role. Each user has a default tenant. 'admin' user is automatically assigned a role in all tenants. The default tenant for 'admin' user is 'admin' tenant.

In order to perform an operation in a tenant that's different from the default tenant for that user, use the extension header 'X-Avi-Tenant' to specify the tenant. If 'X-Avi-Tenant' isn't specified, the operation is performed in the default tenant for that user.

For e.g., when the 'admin' user performs a GET on /api/pool, without specifying 'X-Avi-Tenant', all pools under the 'admin' tenant are retrieved. When the 'admin' user performs a GET on /api/pool specifying 'X-Avi-Tenant' as 'tenant1', all pools under 'tenant1' tenant are retrieved.

Object management

REST methods can be used for managing objects in the Avi Controller.

Object retrieval

Use the GET method to retrieve one or more objects.
To retrieve all tenants: 

GET /api/tenant
{
    count: 1,
    results: [
        {
            “description”: "",
            “url”: "https://10.10.5.27/api/tenant/admin",
            “uuid”: "admin",
            “name”: "admin",
            “local”: true,
            “config_settings”: {
                “tenant_vrf”: false,
                “tenant_default_profiles”: false
            }
        }
    ]
}
To retrieve tenants with uuid ‘admin’: 

GET /api/tenant/admin

{
    "description": "", 
    "url": "https://10.10.5.27/api/tenant/admin", 
    "uuid": "admin", 
    "name": "admin", 
    "local": true, 
    "config_settings": {
        "tenant_vrf": false, 
        "tenant_default_profiles": false
    }
}

Object creation

Use the POST method to create an object.
To create a pool: 

POST /api/pool
{
            "description": "my pool",
            "name": "pool1",
            "servers": [
                {
                    "ip": {
                        "addr": "10.10.1.10",
                        "type": "V4"
                    },
                    "port": 80,
                }
            ],
}

Object modification

Use the PUT method to modify an object.
To modify a pool with uuid ‘pool-13df5490-cb95-47f8-b414-c2b37c897ca7’: 

PUT /api/pool/pool-13df5490-cb95-47f8-b414-c2b37c897ca7
{
      "uuid": "pool-13df5490-cb95-47f8-b414-c2b37c897ca7",
      "name": "p1",
      "tenant_ref": "https://10.10.1.101/api/tenant/admin",
      "servers": [
        {
            "ip": {
                "type": "V4",
                "addr": "10.10.10.10"
            },
            "enabled": true
        },
        {
            "ip": {
                "type": "V4",
                "addr": "10.10.10.11"
            },
            "enabled": true
        }
    ]
}

Object deletion

Use the DELETE method to delete an object.
To delete a pool with uuid ‘pool-13df5490-cb95-47f8-b414-c2b37c897ca7’: 

DELETE /api/pool/pool-13df5490-cb95-47f8-b414-c2b37c897ca7

Response codes

Avi Controller returns the following response codes.

2xx response codes

These response codes are associated with a successful operation.
Response code Description
200 OK - Success
201 CREATED – Successful object creation
204 NO CONTENT – Successfully completed

3xx response codes

These response codes are used for redirection.
Response code Description
302 REDIRECT – Indicates client should use new URL

4xx response codes

These response codes indicate an error.
Response code Description
400 BAD REQUEST – Content is incorrect
401 NOT AUTHORIZED – Authentication failure
404 NOT FOUND – Object doesn’t exist
405 METHOD NOT ALLOWED – Incorrect method on object

5xx response codes

These response codes indicate a server error.
Response code Description
500 SERVER ERROR – Internal server error
503 INITIALIZING – Avi Controller is not ready

Filtering, sorting, paging

The following sections explain how to filter, sort and page objects.

Filtering

To filter a pool by name: 

GET /api/pool?name=pool1
{
    "count": 1,
    "results": [
        {
            "url": "https://10.10.1.101/api/pool/pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "uuid": "pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "name": "pool1",
            "server_count": 1,
            "tenant_ref": "https://10.10.1.101/api/tenant/admin",
            "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
            "use_service_port": false,
            "inline_health_monitor": true,
            "default_server_port": 80,
            "max_concurrent_connections_per_server": 0,
            "graceful_disable_timeout": 1,
            "connection_ramp_duration": 10,
            "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
            "pd_action_type": "POOL_DOWN_ACTION_CLOSE_CONN",
        }
    ]
}

Sorting

To sort a pool by name (in ascending order): 

GET /api/pool?sort=name
{
    "count": 1,
    "results": [
        {
            "url": "https://10.10.1.101/api/pool/pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "uuid": "pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "name": "pool1",
            "server_count": 1,
            "tenant_ref": "https://10.10.1.101/api/tenant/admin",
            "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
            "use_service_port": false,
            "inline_health_monitor": true,
            "default_server_port": 80,
            "max_concurrent_connections_per_server": 0,
            "graceful_disable_timeout": 1,
            "connection_ramp_duration": 10,
            "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
            "pd_action_type": "POOL_DOWN_ACTION_CLOSE_CONN",
        }
    ]
}
To sort a pool by name (in descending order): 

GET /api/pool?sort=-name

Paging

To retrive pools in a specific page with a specific page size: 

GET /api/pool?page_size=1&page=2
{
    "count": 10,
    "next": "https://10.10.1.101/api/pool?page=3&page_size=1",
    "results": [
        {
            "url": "https://10.10.1.101/api/pool/pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "uuid": "pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "name": "pool1",
            "server_count": 1,
            "tenant_ref": "https://10.10.1.101/api/tenant/admin",
            "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
            "use_service_port": false,
            "inline_health_monitor": true,
            "default_server_port": 80,
            "max_concurrent_connections_per_server": 0,
            "graceful_disable_timeout": 1,
            "connection_ramp_duration": 10,
            "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
            "pd_action_type": "POOL_DOWN_ACTION_CLOSE_CONN",
        }
    ]
}

Retrieving specific fields

To retrieve specific fields in the response, use query ‘?fields=field1,field2,field3’. 

GET /api/pool?fields=name,servers,lb_algorithm
{
    "count": 10,
    "results": [
        {
            "name": "pool1",
           "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
          "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
        }
    ]
}