For a long time, actually since we migrated to the VCSA in 6.5 last year, I’ve wanted to utilize the REST API in the appliance to have some monitoring of them.

For several reasons I’ve had to put that on hold, one of them being that there seems to be something wrong with the back-end authentication calls. I get authentication errors on certain calls no matter which user I am logged in with (also the vsphere.local admin account).

1

2

3

4

5

6

7

8

9

10

11

12

{

"type":"com.vmware.vapi.std.errors.unauthenticated",

"value":{

"messages":[

{

"args":[],

"default_message":"Unable to authenticate user",

"id":"vapi.security.authentication.invalid"

}

]

}

}

After deciding to check it more closely I eventually found a few errors in the VCSA logs which in turn led me to this article by Ryan Harris. This error is exactly the same as I have in my environment so I tried the solution given to Ryan by VMware support and this also worked for me.
I have not found any mentions on this error in the Release notes / Known issues of the VCSA so I do think the workaround might be overwritten when updating the appliance but I’ll worry about that later.

If you have the same error please make sure you have backups of your VCSA, and consider contacting support before implementing the fix, especially in a production environment.

With a working API we can now explore the VCSA REST API.

I’ll use Powershell as my REST client. Please note that you can also use the PowerCLI modules for this (CiSServer cmdlets), check out William Lam’s blog series for more info.

To start of I’ll build a couple of variables for the base REST API Url and the specific URL for authenticating.

PowerShell

1

2

3

$vcenter="vcenterserver.your.domain"

$BaseUri="https://$vcenter/rest/"

$SessionUri=$BaseUri+"com/vmware/cis/session"

Now, I’ll create a credential object which I will then create an authentication header from.

As we can see the different health endpoints returns a string value. While this is ok for a quick status it would be nice if we can read out the actual performance values. To do this we’ll use the appliance/monitoring endpoints.

To check the monitoring instances available we’ll start by querying the montioring endpoint

I’ve only outputted the first result, but as we can see we get some information about the different instances, what they are and their ID which we’ll use later on when querying specific resources.

One thing to note is that as we are working with Powershell here and as Powershell is best-friends with JSON objects we can easily output just the different names of the available metrics/resources:

PowerShell

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

PSC:\>$metrics.value|selectname

name

----

com.vmware.applmgmt.mon.name.net.rx.activity.eth0

com.vmware.applmgmt.mon.name.cpu.util

com.vmware.applmgmt.mon.name.net.tx.activity.lo

com.vmware.applmgmt.mon.name.storage.totalsize.filesystem.vcdb_seat

com.vmware.applmgmt.mon.name.storage.totalsize.filesystem.root

com.vmware.applmgmt.mon.name.storage.used.filesystem.netdump

com.vmware.applmgmt.mon.name.storage.used.filesystem.invsvc

com.vmware.applmgmt.mon.name.storage.used.filesystem.root

com.vmware.applmgmt.mon.name.storage.used.filesystem.log

com.vmware.applmgmt.mon.name.storage.totalsize.file

...

In totalt we have 43 metrics available

PowerShell

1

2

PSC:\>$metrics.value.count

43

Let’s try to query a specific metric and check the results of that. For this to work we need to know how to work with the parameters of the API. This is not possible through the API Explorer so you might need to experiment in your own environment first. While you get some information on how it works in the API Explorer be sure to check out the vdc-repo from VMware which has more details for each endpoint.

The API endpoint takes a few parameters that all need to be included. The interval, names, function, start and end time:Interval defines the granularity/interval of the returned values. It ranges from 5 minutes to 24 hours. Check the vdc-repo mentioned above for details.
The names parameter is the actual metrics that you want to retrieve. We can query multiple by adding a sequential number to the parameter (item.names.1, item.names.2 etc).Function specifies the aggregation function, can be COUNT, AVG, MAX, MIN
Finally start- and end_time specifies the range of the query, both must be filled.

We’ll use the “CPU Util” metric in this example and query for 5 minute interval data inside a 10 minute timeperiod.

The result shows 2 values in the data attribute, which corresponds to the 5 minute interval we requested. Note that we’ve used COUNT as the function which in this case should be the SUM inside that interval. If we instead ask for the AVG we’ll get the following output