Identity

Almost all vRA REST APIs require the user to be properly authenticated and authorized. The recommended approach this is through identity service's Bearer Token. Below shows an example of how to use 'curl' to retrieve a Bearer Token and how to use the Bearer Token when interacting with the REST API's. While these examples are geared for Unix and 'curl', you should be able to translate it to any platform or HTTP utility of your choice.

Create variables to make our life easier

To make life easier, we recommend setting environment variables to make your 'curl' commands more readable and flexible. The first variable stores the host of your vRA instance. 

export VRA=vra-host.company.com

Let's also create a variable for the HTTP Accept header, which tells the server what format you want the response to be in. This could also be text/xml. 

export ACCEPT="application/json"

Request a Bearer Token

Next, we will authenticate by requesting a bearer token via a POST against /identity/api/tokens API, and we will store the bearer token in a variable so we can use it on future API invocations. This example passes tony's credentials (for the dev tenant) with inline JSON, but you could also create variables or store this JSON in a file and use the file instead. 

curl -H "Accept: $ACCEPT" -H 'Content-Type: application/json' --data '{"username":"[email protected]","password":"TonysBadPassword","tenant":"dev"}' https://$VRA/identity/api/tokens

NOTE: 'curl' supports an --insecure flag which will return the response even if the traffic isn't secured with a trusted certificate.

If successful, you'll get output similar to the following: 

{"expires":"2014-10-15T19:25:30.553Z","id":"MTQxMzMxNDczMDU0MjplMWI0YzMxZWUzMGQxOGUwOWY4Yzp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLnZtd2FyZS5jb206NGIwODZiODdiYTEzNzE1NzgzOGNmNzFiNzE0YmM0MTk2NTg1ZjllOGVjMTA2MTMwNmJlOTZjNzMwMzQxZTU1ZmViZTgzMjlhYjVlMjQzMzcwNWI2YzNhODBhMjdjOGM0MzlkNmFjOTU1Njc1MDVmNjk3NWU2Njc0MTZmZGQ3NWU=","tenant":"dev"}

The id is the bearer token for you to use on all future API invocations. Set another env variable for this HTTP bearer token to make your life easier. Be sure to use your token rather than the hard-coded example below. Be sure you include Bearer before your token as well, as shown below. 

export AUTH="Bearer MTQxMzMxNDczMDU0MjplMWI0YzMxZWUzMGQxOGUwOWY4Yzp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLnZtd2FyZS5jb206NGIwODZiODdiYTEzNzE1NzgzOGNmNzFiNzE0YmM0MTk2NTg1ZjllOGVjMTA2MTMwNmJlOTZjNzMwMzQxZTU1ZmViZTgzMjlhYjVlMjQzMzcwNWI2YzNhODBhMjdjOGM0MzlkNmFjOTU1Njc1MDVmNjk3NWU2Njc0MTZmZGQ3NWU="

Calling Your First REST API

To verify that everything is setup correctly, use the following example API command to list all identity stores. Be sure to customize the URI with your own relevant tenant if you are running this yourself. 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" https://$VRA/identity/api/tenants/dev/directories

You should get a chunk of unformatted JSON (or XML, depending on your $ACCEPT variable) back. Congratulations! You just invoked your first REST API call directly.

A collection resource will not return every item in the collection. Instead it will use pagination via these request parameters:

Here's a curl example showing how to query catalog-service requests using a custom page size of 50 and returning the second page of the collection. 

curl -H "Accept: application/json" -H "Authorization: $AUTH" "https://$VRA/catalog-service/api/consumer/requests?limit=50&page=2"

Some REST APIs returning a collection will return a links section that will help you traverse a large result set. See example below: 

...

"links": [
    {
        "@type": "link",
        "href": "https://vra-host/catalog-service/api/consumer/requests?page=1&limit=50",
        "rel": "prev"
    },
    {
        "@type": "link",
        "href": "https://vra-host/catalog-service/api/consumer/requests?page=3&limit=50",
        "rel": "next"
    }
],

...

Most REST APIs also return a metadata section that gives you insight into the result set also. See example below: 

...

"metadata": {
    "number": 2,
    "offset": 50,
    "size": 50,
    "totalElements": 125,
    "totalPages": 3
}

...

Sorting

Sorting is performed by passing the $orderby query parameter as described in the OData spec (see section "Query Options"). Both asc and desc are supported for sorting.

For example, to sort catalog-service requests in descending order of the dateSubmitted attribute, one would use: 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/catalog-service/api/consumer/requests?%24orderby=dateSubmitted+desc"

NOTE: %24orderby is the URL-encoded value for $orderby. See the API helpful tips section for more details.

Filtering

Filtering is performed by passing the $filter query parameter as described in the OData spec (see section "Query Options"). Filtering can also be done on nested objects by using a / to identify the child relationship. The following OData filter functions are supported by vRA's REST API:

eq - Equal - /suppliers?$filter=address/city eq 'Palo Alto'
ne - Not equal - /suppliers?$filter=address/city ne 'San Francisco'
gt - Greater than - /products?$filter=price gt 20
ge - Greater than or equal - /products?$filter=price ge 10
lt - Less than - /products?$filter=price lt 20
le - Less than or equal - /products?$filter=Price le 100
and - Logical and - /products?$filter=Price le 200 and Price gt 3.5
or - Logical or - /products?$filter=Price le 3.5 or Price gt 200
not - Logical negation - /products?$filter=not endswith(description,'milk')
( ) - Precedence grouping - /products?$filter=(city eq 'Palo Alto' or city eq 'San Francisco') and price ge 10
startswith - /customers?$filter=startswith(companyName, 'VMw')
endswith - /customers?$filter=endswith(companyName, 'ware')
substringof - /customers?$filter=substringof('Mwa', companyName)

NOTE! substringof uses inverse parameter ordering than other string functions.
length - customers?$filter=length(companyName) gt 5
tolower - customers?$filter=tolower(companyName) eq 'vmware'
toupper - customers?$filter=tolower(companyName) eq 'VMWARE'

The following OData filter functions are not currently supported by vRA's REST API:

OData Filter Examples

Here's an example that filters all catalog-service requests of a specific catalog item name of "Small Linux". 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/catalog-service/api/consumer/requests?%24filter=catalogItem/name+eq+'Small+Linux'"

Here's a another example that leverages the tolower OData function and the substringof function to return requests that completed in a state that contains "success" (after applying the tolower function.) 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/catalog-service/api/consumer/requests?%24filter=substringof('success',tolower(requestCompletion/requestCompletionState))"

Helpful Tips When Interacting with vRA API

Here are some helpful tips that are really important to keep in mind when using vRA's REST API directly.

URL Encoding Is Important and Can Be Tricky

Since the $ character can have special meaning in a command-line context, you might need to URL-encode an $orderby or a $filter to: %24orderby or %24filter. URL encoding is also important for spaces, quotes and double quotes.

Pretty Printing Makes Life Easier

For performance reasons, the server doesn't return the JSON/XML in a pretty-format. However, it's often very helpful to render the output in a readable fashion. One easy way to do this is using bash aliases which leverage python. You can do this from a terminal, or by putting them into your .bashrc 

# Alias to pretty-print XML and JSON using python
        alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"'
        alias ppjson='python -mjson.tool'

Now, by piping the output from curl to this new alias, you can make sense out the output from the command. Here is an example (with the formatted response using the ppjson alias). Use the ppxml alias if your Accept HTTP header variable is text/xml. 

curl -H "Accept: application/json" -H "Authorization: $AUTH" https://vra-host/identity/api/tenants/qe/directories | ppjson

Nested Collections

vRA's implementation of OData doesn't currently support filtering on a nested collection. For example, a single work item may have multiple assignees. When running an HTTP GET on /workitem-service/api/workitems (which will return a collection of workitems), one cannot filter based on the nested collection of assignees.

OData Walkthrough

Now that you know the basics and have seen a few canned examples, here's a walkthrough of how to apply this knowledge to any vRA REST API you are interested in. For this walkthrough, we will be working with the approval-service... but the process should be generic enough to apply to any REST API for any vRA service.

IMPORTANT NOTE: The catalog-service does things a little bit differently, and there are some gotchas that you should be aware of. Look at the catalog-service's OData section for details on this.

  1. Go to the REST API documentation home page for your vRA instance, located at component-registry/services/docs.
  2. Select the service you are interested in. Our example will use approval-service
  3. Read the overview page to get understanding of what the service does if you're not familiar with it
  4. Click on the REST Resource that you want to interact with. Our example will use the pproval Policy REST resource.
  5. Find the REST endpoint that you want to get details from. Our example is interested in retrieving a list of approval policies by doing an HTTP GET against /api/policies
  6. Construct the full URL for the HTTP GET. Use the vRA host name (or load balancer name), appended by the service name, and then append the URI provided by the REST API documentation. Our example will assume the vRA host is: https://vra-host . So the full URL we would use for our HTTP GET would be: https://vra-host/approval-service/api/policies
  7. At this point, you have two options.
    • You can submit your HTTP GET as it is (with no $filter) so you can examine the payload that comes back. Our example using 'curl' might look like: curl -H "Accept: application/json" -H "Authorization: $AUTH" "https://vra-host/approval-service/api/policies"
    • Alternatively, you can navigate to the Data Model associated with the 'Response Body' of your endpoint of interest to get details on the expected JSON/XML.
  8. Now, you can use the JSON payload or the documentation for the return type of the API to craft the $filter expression to meet your needs. Simply use the details about the supported OData functions and the data model to get precisely the data you are interested in. See below for a bunch of examples relating to approval policies to help get you started.

OData Examples for Approval Policies

Example 1: Filtering approval policies based on name.
Examine the data model to see that an approvalPolicy object contains a name string property. The following example filters approval policies that have 'destroy' in their name (and is case-insensitive thanks to tolower) 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/approval-service/api/policies?%24filter=substringof('destroy',tolower(name))"

Below is an example that filters based off exact name 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/approval-service/api/policies?%24filter=name+eq+'Small+Linux+Approval+Policy'"

Example 2: Filtering approval policies based on policy type (nested object).
Examine the data model to see that a approvalPolicy contains a nested approvalPolicyType object. To only return approval policies of types containing a classId of 'resourceActionRequest', you could use the following: 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/approval-service/api/policies?%24filter=policyType/classId+eq+'resourceActionRequest'"

Similarly, to list 'catalogItemRequest' policies, you could use: 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/approval-service/api/policies?%24filter=policyType/classId+eq+'catalogItemRequest'"

Example 3: Filtering approval policies based on state (enum).
Examine the data model to see that an approvalPolicy contains a state property, which is an enum type approvalPolicyState. (The docs for approvalPolicyState show all possible values for this enum). To only return approval policies in a DRAFT state, one would use: 

curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH" "https://$VRA/approval-service/api/policies?%24filter=state+eq+'DRAFT'"