VMware Avi Load Balancer Api
Overview
This manual covers VMware Avi Load Balancer 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
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.
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:
To retrieve tenants with uuid ‘admin’:
Object creation
Use the POST method to create an object.
To create a pool:
Object modification
Use the PUT method to modify an object.
To modify a pool with uuid ‘pool-13df5490-cb95-47f8-b414-c2b37c897ca7’:
Object deletion
Use the DELETE method to delete an object.
To delete a pool with uuid ‘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:
Sorting
To sort a pool by name (in ascending order):
To sort a pool by name (in descending order):
Paging
To retrive pools in a specific page with a specific page size:
Retrieving specific fields
To retrieve specific fields in the response, use query ‘?fields=field1,field2,field3’.