Avi – API Parameters and Filters

Avi’s platform is built on APIs. You can take a look at the official API guide here. It’s a pretty comprehensive list of all the APIs and the methods available, as well as some examples on how to use the API including authentication. Additionally, swagger is built into all the Avi controllers, so you can always test out your API queries there.

This blog post is mainly going to be about the extra fields that are available as part of the Avi API. Things like: filtering content, searching, includes, excludes.

Also this is not necessarily a comprehensive list. The API can change at any time, and some of the below might be outdated. The BEST way to see what’s available in the API is to check the latest official documentation or experiment in the Avi UI yourself.

Software Versions used in this demo

Software	Version
Avi Controller & Service Engines	22.1.5

Use the Developer Tools in your Browser

If you could take away just one useful thing from this blog, it would be to learn to navigate the developer tools on your browser. Since Avi is an API first platform, everything you see in the UI will essentially be calling backend APIs. So if you want to learn about the latest parameters or filters, I would start there.

As you can see above, just by clicking on one of my virtual services, you can see at least 5 different APIs that were called. Actually there were way more than that, and they’re all visible in the Network section of the developer tools.

You can select the API call that you would like to inspect and Copy the link address. Example: https://avi-controller.home.lab/api/virtualservice-inventory/virtualservice-5b091f06-7f6a-4d0f-85fc-b108e9ab6c2a/?include_name=true&include=health_score%2Cruntime%2Calert%2Cfaults&step=300&limit=72&

Now we have all the configuration, runtime information, and the health score of the virtual. Just by adding a few parameters to the API.

Avi API Parameters and Filters

Here’s the list of API parameters and filters that we’ll discuss in detail.

Parameters

• include_name
• sort
• fields
• skip_default
• page_size
• page

Filters

• name.contains
• name.icontains
• name.in
• search
• isearch
• cloud_ref.uuid
• cloud_ref.name
• limit_by
• label_key
• label_value

Testing the Filters and Parameters

I’ve found the easiest way to test out the API is to simply login to the Avi controller, and rewrite the URL.
https://YOUR-CONTROLLER-URL/api/pool

That way you don’t have to use any tools like Insomnia or Postman, or any scripting languages to test these.
If your JSON doesn’t look as pretty as the above, your browser needs a json formatter plugin. Here is the one I use for Chrome.

Parameters

include_name

The first parameter that we’ll look at is include_name. This param is VERY useful if you need to convert the UUIDs into a name. Adding this param into the URI, will append the name of the object, at the end of the uuid.

https://avi-controller.home.lab/api/pool?fields=cloud_ref,name,health_monitor_refs&include_name=true

sort

This is pretty useful, especially if you have 100s of objects to look through. A good example here would be to sort all the objects by last modified date. I’ll sort the pools on my Avi controller, by _last_modified.

https://avi-controller.home.lab/api/pool?sort=_last_modified

In my output above, you will see all the pools are sorted by their modified date. You could also sort on “name” and have them alphabetized.

fields

Use this param if you want to reduce the returned data, to only the fields you’d like to see. Avi objects can have lots of fields, and if you have 1000s of those objects, like virtuals or pools, then it can take a while to process that API request. Using fields, you can reduce the return payload and get responses faster.
In the example below, I want to see all the pools on my controller, but just the names of the pools, any associated health monitors, and the cloud.
https://avi-controller.home.lab/api/pool?fields=cloud_ref,name,health_monitor_refs&include_name=true

FYI uuid is in there by default, and I don’t believe it can be removed.

skip_default

Again another very useful command for reducing returned data. Adding “skip_default=True” to the URI, will remove any fields which contain only default information. I have a lab setup with 5 pools, and using this command reduced the data from 418 lines to 187.
https://avi-controller.home.lab/api/pool?skip_default=True

As you can see in the above diff, sections like “analytics_policy” and “conn_pool_properties” were skipped.

page_size & page

This is used for pagination, especially useful with large controllers and 100s or 1000s of objects. This is not as useful in a lab with 5 pool members, but we can still test it. page_size allows you to specify how many objects you would like returned per page. So if I do a page_size of 2, then I would expect to see 2 pools on the first page, and if I go to page 2, then I would see the next 2.
https://avi-controller.home.lab/api/pool?fields=name&page_size=2&page=1
I reduced the data by showing only the “name” field.

On to page 2… The next 2 pools…

On to the final page, 3…

One very important thing to note, is that the field “next” is no longer on the last page. So if you were to automate this with a scripting language, you could increment the page by 1 as long as the field “next” is present in the data.

Filters

name.contains & name.icontains

You can use these filters to search the name within an object. For example, if you want to look through your pools, and return all the pools with “qa” in them.
name.contains – case sensitive
name.icontains – case insensitive
https://avi-controller.home.lab/api/pool?fields=name&name.icontains=qa

2 of the 5 pools were returned as results…

In general, with network devices/objects I would always recommend keeping things all lowercase. It makes life easier, at least from my perspective. If you do have case sensitive names, then feel free to use the name.contains, that’s what it was designed for.

I couldn’t figure out how to send an uppercase “QA” in the browser, so i’ll forgo that example.

name.in

This filter is used if you know the name of the object/s and specifically want to see their output combined into a single data return. An example would be to get both of the QA pools in my lab, and only those pools.
https://avi-controller.home.lab/api/pool?fields=name&name.in=qa-pool1,qa-app-2

As you can see I had to specify the exact name of the pools above, comma separated.

I had never actually used this filter before and it definitely seems like it could reduce the number of calls to the API, especially with regard to automation. In the past, I would simply get a list of the UUIDs, and query the API for each of the pool uuids.

In the above example, it would take 2 API calls to retrieve the pool data for both of the QA pools. Much less efficient, definitely use the name.in filter.

search & isearch

This is probably my favorite filter. It is just so powerful and useful, when used correctly. As the name implies, you can search through the objects, and if any of the values in any of the fields match your search string, then it will be returned as part of the results.

You can use the search filter in either of 3 ways.

1. search=LEAST_CONN – Return all objects that contain the search string as a value in any field
   • Even a partial match is successful since, LEAST_CONN is in the string LB_ALGORITHM_LEAST_CONNECTIONS
2. search=(name,qa) – Return all objects that has “qa” in the name field
   • Remember, even a partial match is successful.
3. search=(health_monitor_refs,) – Return all objects that has the field “health_monitor_refs”

Example 1: Provide a list of pools that have a specific server

https://avi-controller.home.lab/api/pool?fields=name,servers&search=8.8.8.8
There are 2 pools that have the 8.8.8.8 server, so I’d expect to see only those 2 pools returned.

Example 2: Provide a list of pools that have an active health monitor

I have 2 pools with an active health monitor. The other pools only have a passive health monitor. So if we search for pools with HMs, I expect to only see 2.
https://avi-controller.home.lab/api/pool?search=(health_monitor_refs,)

cloud_ref.uuid & cloud_ref.name

Useful to return all the objects that are in a particular cloud. Cloud in Avi terms, refers to the environment that a particular application is hosted. So we have different clouds for various architectures, like vCenter cloud, NSX-T cloud, AWS, etc…
So this filter could be used to search through all the pools on an Avi controller, and return only the pools in the “vcenter” cloud.

If you know the uuid of your cloud, use the cloud_ref.uuid. Otherwise you can always use the cloud_ref.name filter instead.
https://avi-controller.home.lab/api/pool?fields=name&cloud_ref.name=vcenter

https://avi-controller.home.lab/api/pool?fields=name&cloud_ref.uuid=cloud-9929656c-c7d4-4550-b747-42818abecebd

limit_by

As the name implies, this filter will limit the results returned. Honestly, I’ve only used this filter when looking at logs or metrics, like if you want to see the past 10 alerts or something. But you can technically use it for other objects as well, like pools.
https://avi-controller.home.lab/api/pool?fields=name&limit_by=3

Notice how it doesn’t give you a “next” or any indicator that there are more pools available…

label_key and label_value

In Avi, labels are generally added to objects for use with RBAC, and I have a blog post dedicated to the advanced rbac features if you’re interested. So I would say that this filter is especially useful if you’re trying to determine what objects are going to be visible for users, based on the roles they are assigned.

You can use these filters in 3 ways

1. label_key=app – Return all objects that have the KEY as “app”
   • So regardless of their value, if they have that key, then return it in the response
2. label_value=prod – Return all objects that have the VALUE as “prod”
   • So regardless of their Key name, if they have “prod” anywhere in their value, then return it in the response
3. label_key=app&label_value=prod – Return all the objects that have BOTH the KEY and the VALUE
   • This is probably the best option, since usually if you’re searching labels, you would want to match the key and value together.

Example 1: Search pools for key “app” and value “prod”
https://avi-controller.home.lab/api/pool?fields=name,markers&label_key=app&label_value=prod

Example 2: Search pools for value “prod”.
https://avi-controller.home.lab/api/pool?fields=name,markers&label_value=prod

2 pools show up now. 1 with a key of “tiger” and the other using the correct key of “app”