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

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 name	Obtain vRA Token
   Type	REST
   Action	POST
   URL	https://your-vra-server-fqdn/csp/gateway/am/api/login?access_token
   Payload	{ "username":"administrator", "password":"LetM31n!" }
   Headers	Accept 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 name	Get All Cloud Accounts
   Type	REST
   Action	GET
   URL	https://your-vra-server-fqdn/iaas/api/cloud-accounts
   Headers	Accept 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.

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

 

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.

 

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