Several articles on basic usage have been written on iControl REST (see the resources at the bottom of this article) so the intent here isn’t basic use, but rather to demystify some of the finer details of using the API. The first article covered URI specifics, the second article discussed subcollections, and this third article will cover query parameters.
Query Parameter Definitions
F5 has documented a number of query parameters that can be passed into iControl ReST calls in order to modify their behavior. The first set follows the OData (open data protocol) standard. The filter parameter also supports several operators.
$filter
$select
$skip
$top
Yes, the dollar sign is important and necessary on these parameters. The operators you can use on these parameters are below. Note that the eq operator can only be used with the filter.
eq - equal
ne - not equal
lt - less than
le - less than or equal
gt - greater than
ge - greater than or equal
Logical Operators:
and
or
not
Beyond the OData parameters, there are a few custom parameters as well.
expandSubcollections - allows you to get the subcollection data in the initial request for objects that have subcollections.
options - allows you to add arguments to the tmsh equivalent command. An example will be shown below.
ver - This is for the specific TMOS version. Setting this parameter guarantees consistent behavior through code upgrades. Please note that the JSON return data for a number of calls has changed between the initial release in 11.5.0 and the current release. No items have been removed, but key/value pairs in the output have been added.
Note the lack of a dollar sign on the custom parameters.
Example #1 - Filter
Now that we have the parameters and operators defined, let’s take a look at some examples. First, we’ll take a look at the $filter parameter. If you want to limit your results to a particular partition, your URL will look something like this:
I didn’t post the return data from example 1 because it’s a lot of data, even for a small set of returned results. Most of it is all the fields in a pool that are there and important, but default and not of as immediate importance as others. This is where the $select parameter comes in. If you just want to take a look at the name of the pool and say the load balancing mode, your URL will look like this (still filtering for the staging partition:)
For larger sets of data, you can page through the objects in chunks with $top and $skip. If $skip is not specified when $top is used, it behaves as though set to 0. Please note, however, that paging is restricted to collections and sub collections, so whereas this would work to page through the defined data groups, it would not work to page through the records of a data group. Let’s add the top parameter to our previous URL:
So we got the same data back as before, only 2 items instead of the original 5, as well as some additional fields that weren’t there previously. Note that once $top is used, the key/value pairs “nextLink”, “currentItems”, and “totalItems” are added to the response. “nextLink” is the URI that will grab the next $top number of results from the query. If you parse this value and use it (once you have replaced the localhost with your actual host information), you will not have to perform any paging calculations. “currentItems” tells you how many items have been returned in the current call. If this value is less than $top, then you know you have reached the end of the items. “totalItems” tells you how many items would be returned if one did not page using $top.
Example #4 - Options
For this next example, we’ll start with tmsh. If you want to get the connections on the BIG-IP, you type “tmsh show sys conn” at the command line. This can be a very large set of data, however, so there are options on the command line to narrow this down, like cs-client-addr, cs-client-port, and so on. So a narrowed down request at the command line would look like “tmsh show sys conn cs-client-addr 10.0.0.1 cs-client-port 62223.” To translate this command to an API request, you need to use the options parameter
For our final example, we’ll use the expandSubcollections parameter. This is useful for querying objects like pools that have subcollections. Without the parameter specified, the pool data is returned with the specification that pool members is a subcollection, but doesn’t return the set of pool members. By providing the parameter, the pool members are returned along with the pool definition (only first one shown for brevity.)
If you want to select just the name and address from the pool members in the previous example, it's not as simple as adding the $select=name,address to that query. Remember from the earlier article about your object/component/sub-component tiers. Instead, you need to specify the members subcollection in the URL, then attach your select parameter.
It is very important to filter your results when you are expecting a lot of output in the return. One can easily cause problems by overloading the management network.
@bahoug, yes this is possible:
https://172.16.44.15/mgmt/tm/ltm/persistence/persist-records?options=client-addr+192.168.102.1
Results from my local query:
{
kind: "tm:ltm:persistence:persist-records:persist-recordsstats"
selfLink: "https://localhost/mgmt/tm/ltm/persistence/persist-records?options=client-addr+192.168.102.1&ver=12.0.0"
apiRawValues: {
apiAnonymous: "Sys::Persistent Connections source-address 192.168.102.1 192.168.102.60:80 192.168.103.10:80 (tmm: 0) Total records returned: 1 "
}-
}
@JRahm I'm guessing the reason I cant get it to work is I am running 11.5.1. I see in your self link you are using v12.0. Your example is exactly what I am looking for to delete persistence records and system connections. I've seen a few other examples that call cli scripts from the restAPI, however its not as elegant as just being able to use the restAPI. BTW this is a great article thanks for putting it together.
I'll fire up an 11.5 image tomorrow and test, it should work as is (minus the version parameter) in all versions, but I'll take a look at the tmsh command in 11.5 and make sure the rest version works as well.
I was able to run these examples against my environment running version 11.5.3
i have a couple of questions:
I'm getting could not resolve GET when using in version 11.5.3
Does Anybody have tips on how to manipulate the output to get a clean formatting?
Thank you
This doesn't work everywhere on all collections. For example, if I am looking for the software version and hotfix currently running, the select has no effect here:
curl -k -u admin:myPassword -H "Content-Type: application/json" -X GET https://10.19.1.10/mgmt/tm/sys/software/status?$select=active,version,build -d "" | python -m json.tool
This doesn't work everywhere on all collections. For example, if I am looking for the software version and hotfix currently running, the select has no effect here:
curl -k -u admin:myPassword -H "Content-Type: application/json" -X GET https://10.19.1.10/mgmt/tm/sys/software/status?$select=active,version,build -d "" | python -m json.tool. Nothing gets filtered. I get everything
I'm looking for a way to read the total number of persist-records without the actual records. So I can check if the cluster is in sync.
How can I accomplish this with a Rest API call?
Can you filter on anything other than the partition attribute? Only being able to filter on that attribute seems to have little value. When I try other attributes I get an error like these:
Query parameter $filter has invalid value allowNat eq yes.
Query parameter $filter has invalid value monitor eq ~Common~http.
I'm testing against 11.5.4
per the user guide, the odata filter parameter is not fully implemented, so partition at this point is the only supported function for most modules. ASM, however, does support more filter functionality. Please consult the user guide.
Great article! It helped me overcome some of the filtering issues I had with BIG-IQ CM REST API as well.
However, one that I am not able to figure out yet is to select BIG-IP hostnames form a dynamic device group:
Like GET: https://{{bigiq_mgmt}}/mgmt/shared/resolver/device-groups//devices?$select=hostname
It still returns the full details of all devices in that group.
In case someone has an advice on how to get only the devices hostnammes, managementAddress, that would be much appreciated.
Is there a way to filter on Subcollections? such as this.... mgmt/tm/ltm/pool?expandSubcollections=true&$filter=partition eq 'partition name' ..... This will display all the pools and their pool members but I want to further filter down and only show the partition, pool name, pool member, pool member ip and the monitor. I can't seem to find any query examples on how to filter or select within a Subcollection. Thanks
Thanks so much for your reply but I have found something that has got me the information that I needed. Le me know your thoughts. I will post my output below minus the server names for security purposes
