Introduction

In this post I will be providing an example of

  • how to make REST API calls from Code Stream
  • obtain an API token from the vRA 8.3 REST api
  • obtain a list of Cloud Accounts registered with vRA
  • filter for a specific Cloud Account on vRA

 

Assumptions

I have made a few assumptions that you should note before we begin

  • vRA 8.3 – You have a basic level of understanding of vRA, for example, how to navigate around and get to different places in the UI
  • Code Stream Knowledge – You will need to have some knowledge of Code Stream, such as how to create a new pipeline, create Stages and Tasks, edit them and execute pipelines.

 

Prerequisites

You must meet the below prerequisites to follow along with this blog post.

  • vRA 8.3 Configuration – You have a configured vRA 8 instance with a Cloud Account
  • Code Stream Pipeline – you will need a new pipeline created and ready for you to configure new Stages and Tasks in

 

The History Lesson

[editor – excuse his jokes..]

REST has been around since 1994 when it was first introduced in the HTTP 1.1 standard, although, it wasn’t until around the year 2000 where it was defined and documented and become what we now know as REST. The principal of REST is to promote an image of how a web application is comprised, of multiple service endpoints with resource operations such as POST, GET and PUT. In fact, the term REST supports this, as it stands for ‘Representational State Transfer.’ In the past SOAP was a widely used transport, still used today in vSphere in fact. vRA 8.x supports REST which in turn allows us to make API calls to its’ service endpoints over the Http protocol. And on that note, schools out for summer!

 

Making REST Calls

There are lots of software packages that you can use to make REST calls and test out access to endpoints and systems. In itself, Code Stream contains a REST task that takes care of all the code complexity for us. We can make the calls with little knowledge, simply providing the method (for example, POST or GET), header content, body content and the specific endpoint that you want to communicate with. The REST response values can be extracted and used in subsequent tasks where required.

 

Authentication

Obviously communicating with a service is going to require authentication. vRA handles this by accepting a username and password of a registered user in vRA. If authenticated successfully, a token will be issued. This token is then used in subsequent calls to the vRA service endpoints, being passed in the header of the REST request. Let’s start by obtaining a token.

  1. Create a new Stage. I have called mine Initialization.
  2. Within this stage, create a new Task and configure it as per the information below. Note that you will need to insert your own vRA FQDN into the URL where the placeholder is. You will also need to specify a username and password for an account configured with access rights to vRA. Of course, I have kept this simple, but I would recommend configuring the username and password as variables (type Secret) and then pass these in here.
    Task nameObtain vRA Token
    TypeREST
    ActionPOST
    URLhttps://your-vra-server-fqdn/csp/gateway/am/api/login?access_token
    Payload{
    "username":"administrator",
    "password":"LetM31n!"
    }
    HeadersAccept
    application/json

    Content-Type
    application/json
  3. You can click Save and execute your pipeline. If you have configured things correctly, then you should be able to follow the pipeline execution and view the response from the REST call. Your response should look similar to the one in the screenshot below. You should see the token in the response. In our next REST call, we will pass this token in the requests Header to ensure our request is authenticated.

    The REST response should include a token for you to use in subsequent calls

Request All Cloud Accounts

Now we have our token, let’s use it to make a REST request to obtain a list of all of the Cloud Accounts configured on our vRA instance.

  1. Create a new Stage. I have called mine Get Cloud Accounts.
  2. Within this stage, create a new Task and configure it as per the information below. Note that you will need to insert your own vRA FQDN into the URL where the placeholder is.
    Task nameGet All Cloud Accounts
    TypeREST
    ActionGET
    URLhttps://your-vra-server-fqdn/iaas/api/cloud-accounts
    HeadersAccept
    application/json

    Content-Type
    application/json

    Authorization
    Bearer ${Initialization.Obtain vRA Token.output.responseJson.access_token}
  3. You can click Save and execute your pipeline. If you have configured things correctly, then you should be able to follow the pipeline execution and view the response from the REST call. Your response should look similar to the one in the screenshot below. Note that the REST response contains a JSON object detailing each of the Cloud Accounts configured in vRA.

The token will be used to authenticate the call to get all of your Cloud Accounts

You may have a question at this point. How did the token from the Authentication call get used in the call to get Cloud Accounts? The answer lies in one of the header entries that we included. The header entry in question is the Authorization entry. The value for this entry feeds in the output of the Obtain vRA Token task. We can break this down as per below. Note that we include the word Bearer at the start of the value as well. Each entry is ‘.’ [dot] delimited and follows the hierarchy of stage -> task -> output -> response body -> response value

We can see how we provide the path to our response value using a dot delimited path

 

Requesting A Specific Cloud Account

Now you have the ability to request all of the cloud account details, you can narrow this down by appending a query string to the REST request’s url. For example, if we change the url as follows, we can filter out all results that do not match the query ‘cloud account name equals aprovc1.automationpro.lan‘ and return that single result.

Appending a query string to our URL allows us to apply filters to our results

 

If you are wondering where you can get a list of these filters from, you can check out the API documents that are hosted on your vRA 8.3 instance. Additionally, the information provided here is mostly correct with some solid examples of varying query syntax.

 

 

Footnote: image attribution on this post: Photo by Victoria Tronina on Unsplash

paul_davey

CIO at Sonar, Automation Practice Lead at Xtravirt and guitarist in The Waders. Loves IT, automation, programming, music