Getting Started with the VMware Aria Automation REST API

While VMware Aria Automation Orchestrator 8.x includes a plug-in, workflows, and actions for automating VMware Aria Automation, I often find these workflows and actions to be simple and nowhere close to supporting the extensibility outcomes I require. Instead, I frequently must work directly with the VMware Aria Automation REST API. At first, the idea of writing code to utilize the API seemed a bit daunting, but with the help of the Aria Automation 8.7 Extensibility Migration Guide Samples, I quickly learned that working with the API wasn’t too tricky.

The VMware Aria Automation REST API consists of several endpoints that cover essentially all functionality within the product. I find myself interacting most often with the “Approvals”, “Deployments”, “Infrastructure as a Service”, and “Policies” end-points. However, there are several additional areas to explore, as documented in the VMware Aria Automation REST API Documentation. This documentation can be accessed directly from your VMware Aria Automation deployment by pointing your web browser to https://<aria automation URL>/automation-ui/api-docs/. Below is a screenshot showing the various API endpoints that are available to us.

Now that we’ve had the opportunity to explore what’s possible in the VMware Aria Automation REST API, we will get to the technical content of this blog post. I will walk through how to get started with the VMware Aria Automation REST API within VMware Aria Automation Orchestrator. In future posts, I will cover ways to improve our code to be more reliable, to support API versioning, and to allow for easy reuse and expandability into most REST API use cases by writing as little additional code as possible. For now, though, we will start with the basics of authenticating against the REST API and making our first request.

Authentication

While you might expect that authentication against the REST API would involve obtaining credentials, requesting a token from the API by providing our credentials, and then providing the token with each request, you’d be wrong. Fortunately, the VMware Aria Automation plug-in for VMware Aria Automation Orchestrator makes this process easy. Before getting into the code, it should be noted that this blog post assumes that the VMware Aria Automation plug-in has already been configured within your deployment of VMware Aria Automation Orchestrator.

To get started, I created a new Action within VMware Aria Automation Orchestrator called getProjects with a return type of an array of Properties. I will also add an input variable named vraHost of type VRA:Host that will allow us to specify the instance of VMware Aria Automation to target. This variable is used to pass in the plug-in’s connection for use within our code. Next, we utilize the VRA:Host resource to create a new authenticated REST API client using the following code:

//Create REST client
var client = vraHost.createRestClient();

The client variable is now an authenticated REST API client that we can use to execute REST API calls to our VMware Aria Automation deployment. Easy, right? With the authentication portion of the exercise out of the way, our next step is to utilize the REST API to get our data.

Requesting Data

For this example, we will execute a rather basic query against the REST API to return all projects defined within our deployment. The results from the REST API call will be returned from our Action as an array of Properties. Before executing our REST API request, we must create a request object utilizing the REST API client we just generated. To do this, we first must understand what information is required to build the request. Here is a copy of the documentation for the API:

The three inputs needed for the function are :

• method (string) – the HTTP method used in our request (GET, PATCH, POST, PUT, or DELETE)
• path (string) – the path to the API endpoint
• requestPayload (string) – the body of our HTTP request in JSON format

In our example, we want to get all projects from VMware Aria Automation, so our method will be “GET”. The REST API documentation provides the path that the request will use. In this example, the path will be “/iaas/api/projects”. If we want to filter the results of our request, we could include additional query parameters in the path, but in this example, we want the REST API to return all projects. Finally, our requestPayload will be null as we are not providing any data to the REST API when executing a GET request. The code to generate our request looks like this:

//Create REST request object and populate values    
var request = client.createRequest("GET", "/iaas/api/projects", null);

Next up, we execute the request using with the following code:

//Execute REST request and set output to the response variable
var response = client.execute(request);

The requests return object is of type VraRestResponse, which contains several properties of interest. One of the fields of interest is the statusCode of the response. I utilize this code to determine if the request was successful by looking for a 200 or 204 response code. The REST API documentation will provide information on which response codes to expect and what each code means. If the response code is not 200 or 204, I can assume that our request was unsuccessful and throw an error; otherwise, I continue with the code execution. I utilize the following code for this check:

//Check for valid HTTP 2xx response code, otherwise throw error and return response data
if (!(response.statusCode >= 200 && response.statusCode <= 204))    
throw  "HTTP " + response.statusCode + " - " + response.statusMessage + " : " + response.contentAsString;

The content returned from the REST API is a string containing JSON data that, in its current form, is not all that useful to us within Aria Automation Orchestrator. The following is the JSON string returned during my execution of the code:

{
    "content": [
        {
            "administrators": [
                {
                    "email": "admin-user-1",
                    "type": "user"
                }
            ],
            "members": [
                {
                    "email": "user1",
                    "type": "user"
                }
            ],
            "viewers": [],
            "supervisors": [],
            "zones": [
                {
                    "zoneId": "c01d867f-c2c3-4b49-a805-2c111b274c08",
                    "priority": 0,
                    "maxNumberInstances": 0,
                    "allocatedInstancesCount": 0,
                    "memoryLimitMB": 0,
                    "allocatedMemoryMB": 0,
                    "cpuLimit": 0,
                    "allocatedCpu": 0,
                    "storageLimitGB": 0,
                    "allocatedStorageGB": 0.0,
                    "id": "29b8baa5-6f84-439f-bf31-9547bfed4e89-c01d867f-c2c3-4b49-a805-2c111b274c08"
                }
            ],
            "constraints": {},
            "operationTimeout": 0,
            "sharedResources": true,
            "placementPolicy": "DEFAULT",
            "customProperties": {},
            "name": "Project 1",
            "description": "",
            "id": "29b8baa5-6f84-439f-bf31-9547bfed4e89",
            "organizationId": "f1d3db17-33b4-4fe5-81d9-a72146dec724",
            "orgId": "f1d3db17-33b4-4fe5-81d9-a72146dec724",
            "_links": {
                "self": {
                    "href": "/iaas/api/projects/29b8baa5-6f84-439f-bf31-9547bfed4e89"
                }
            }
        },
        {
            "administrators": [
                {
                    "email": "admin-user-2",
                    "type": "user"
                }
            ],
            "members": [
                {
                    "email": "user2",
                    "type": "user"
                }
            ],
            "viewers": [],
            "supervisors": [],
            "zones": [
                {
                    "zoneId": "c01d867f-c2c3-4b49-a805-2c111b274c08",
                    "priority": 0,
                    "maxNumberInstances": 0,
                    "allocatedInstancesCount": 0,
                    "memoryLimitMB": 0,
                    "allocatedMemoryMB": 0,
                    "cpuLimit": 0,
                    "allocatedCpu": 0,
                    "storageLimitGB": 0,
                    "allocatedStorageGB": 0.0,
                    "id": "c67da407-a93e-4eb2-8399-1afa65c4db6e-c01d867f-c2c3-4b49-a805-2c111b274c08"
                }
            ],
            "constraints": {},
            "operationTimeout": 0,
            "sharedResources": true,
            "placementPolicy": "DEFAULT",
            "customProperties": {},
            "name": "Home Lab",
            "description": "",
            "id": "c67da407-a93e-4eb2-8399-1afa65c4db6e",
            "organizationId": "f1d3db17-33b4-4fe5-81d9-a72146dec724",
            "orgId": "f1d3db17-33b4-4fe5-81d9-a72146dec724",
            "_links": {
                "self": {
                    "href": "/iaas/api/projects/c67da407-a93e-4eb2-8399-1afa65c4db6e"
                }
            }
        }
    ],
    "totalElements": 2,
    "numberOfElements": 2
}

Instead, we must convert this JSON data into an object, allowing us to easily reference the various properties within the response data. To do this, we use the following code:

//Convert JSON response into an object
var object = JSON.parse(response.contentAsString);

If the request is successful, the content property of the object variable contains an easy-to-reference array of VMware Aria Automation projects within the deployment. We can return this object from our VMware Aria Automation Orchestrator action using the following code:

//Return the array of projects
return object.content;

As shown below, after executing the code, I get back an Action Result that is an array of Properties containing our VMware Aria Automation projects:

If I expand the Action Result, I see that entry in the array and if I expand it further, it provides the details for each project as shown:

Seems simple enough? While the response data might appear correct if the instance of VMware Aria Automation has a small number of projects, we must pay close attention to the fact that the REST API documentation states that only 20 objects are returned by default unless we set a different value for the size parameter in our request. While it might be tempting to provide a very large value for the size parameter, such as 5000, this would not be wise, and in situations where there is the potential for more records to exist than we planned, the code would fail to provide the expected results. Instead, we must correctly handle the REST API response and utilize the additional properties returned in the response data to implement paging.

My next article in this series will walk through processing paged responses from the REST API to ensure we always obtain the expected results regardless of record count. In future blog posts, we will update our code to handle parameters, API versioning, and input encoding. We also will create VMware Aria Automation Orchestrator actions that can be reused to simplify all future API requests.

Share:

Search

Get Notified of Future Posts

Follow Me

Recent Posts