vRealize Automation REST API with Curl

Posted on February 7, 2015 by Ryan Kelly — 18 Comments ↓

vRealize Autmation exposes a RESTful API to automate common tasks without having to access the GUI. Some common examples of why you would use this are:

Request machines as part of a Continus Integratation process
Integrate vRA provisioning into your build systems such as Jenkins
Drive vRA requests from a third party IT management portal
Trigger Day 2 operations from monitoring or testing systems, for example triggering a reboot of a machine.

Pre-reqs that you will need in place prior to exploring the REST API

vRealize Automation:

The REST API is officially supported in vCloud Automation Center 6.1 and vRealize Automation 6.2 and all newer versions.
At least one IaaS catalog item to provision. NOTE: You should be able to provision this successfully from the UI prior to using the API.

User Workstation:

A linux or Mac with curl
Network access to the vRA appliance and the SSO appliance
A few hours of free time where you will not be interupted

API Documentation here

You should also be able to follow this lab by using the VMware Hands on Labs On-line

Lets get started, first we will need to set some environment variables to save us time. Let’s export the vRA appliance host name.

Note: Replace the text in red with your appliance host name

export VRA=vcac-01a.corp.local

Create variable for the HTTP Accept header, which tells the server what format you want the response to be in. Could also be application/json

export ACCEPT="text/xml"

Here 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 cloudadmins credentials (rainpole tenant) with inline JSON, but you could also create variables or store this JSON in a file and use the file instead.

I have highlighted what you need to change for your environement:

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data '{"username":"cloudadmin@corp.local","password":"VMware1!","tenant":"rainpole"}' https://$VRA/identity/api/tokens

Once you press enter you should see a response like this.

Notice in the above the “id” field is what we need to copy and paste to create our AUTH variable

Now let’s export our Authentication token to a new variable with export AUTH=”Bearer youridfromcommandabove”

Notice it must include Bearer and a space and be in quotes for this to work. For example:

export AUTH="Bearer MTQyMzI2Mjc5NTMzNzphNTM0ODg2NTI1NjY4OGVmNGFmYjp0ZW5hbnQ6cmFpbnBvbGV1c2VybmFtZTpjbG91ZGFkbWluQGNvcnAubG9jYWw6ZTYzZDJiMDkwYTMzYzM3OTg4ZDQwNWYxZWYwMTcxZjIwMzgwZGFjNTliNWE5ZGExYTVlOTk0ZWNjNmEwNzk3MjUxYWNjMDlhMTllNTZkY2JhYmRhNjE4ZGU5YmE5M2FmZjQ3Y2MwMjI0ODg2M2MxZmUzNWI3NjI2Y2Q3OTI3Yzg="

You need to change the red text to your authentication id

Now lets test connectivity by listing the entitled catalog items with curl –insecure -H “Accept: $ACCEPT” -H “Authorization: $AUTH” https://$VRA/catalog-service/api/consumer/entitledCatalogItems

curl --insecure -H "Accept: $ACCEPT" -H "Authorization: $AUTH" https://$VRA/catalog-service/api/consumer/entitledCatalogItems

Now we need to construct a JSON file for our request. You can get the fields you need by traversing the API. I have highlighted the fields you need

{
 "@type": "CatalogItemRequest",
 "catalogItemRef": {
 "id": "908259ad-555c-40fc-9ef1-24281f4ff42b"
 },
 "organization": {
 "tenantRef": "rainpole",
 "subtenantRef": "df59b474-7374-48f0-ab08-e11d8cdc2298"
 },
 "requestedFor": "cloudadmin@corp.local",
 "state": "SUBMITTED",
 "requestNumber": 0,
 "requestData": {
 "entries": [
 {
 "key": "provider-blueprintId",
 "value": {
 "type": "string",
 "value": "c2e64049-2f4f-439b-adc3-88c10cef17ea"
 }
 },
 {
 "key": "provider-provisioningGroupId",
 "value": {
 "type": "string",
 "value": "df59b474-7374-48f0-ab08-e11d8cdc2298"
 }
 },
 {
 "key": "requestedFor",
 "value": {
 "type": "string",
 "value": "cloudadmin@corp.local"
 }
 },
 {
 "key": "provider-Machine.ssh",
 "value": {
 "type": "string",
 "value": "true"
 }
 },
 {
 "key": "provider-VirtualMachine.CPU.Count",
 "value": {
 "type": "integer",
 "value": 1
 }
 },
 {
 "key": "provider-VirtualMachine.Memory.Size",
 "value": {
 "type": "integer",
 "value": 1024
 }
 },
 {
 "key": "provider-VirtualMachine.Disk0.Size",
 "value": {
 "type": "string",
 "value": "6"
 }
 },
 {
 "key": "provider-VirtualMachine.LeaseDays",
 "value": {
 "type": "integer",
 "value": 5
 }
 },
 {
 "key": "provider-__Notes",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.TotalStorageSize",
 "value": {
 "type": "decimal",
 "value": 0
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.Description",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
 "value": {
 "type": "integer",
 "value": 1
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.Reason",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.AssignToUser",
 "value": {
 "type": "string",
 "value": "cloudadmin@corp.local"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.MinCost",
 "value": {
 "type": "string",
 "value": "0.9329"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.MaxCost",
 "value": {
 "type": "string",
 "value": "0.9329"
 }
 },
 {
 "key": "description",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "reasons",
 "value": {
 "type": "string",
 "value": "Test"
 }
 }
 ]
 }
 }

Save this file and your ready to request. I saved mine as centos.json

Now let”s request with the following:

curl –insecure -H “Accept: $ACCEPT” -H “Authorization: $AUTH” https://$VRA/catalog-service/api/consumer/requests –data @/centos.json –verbose -H “Content-Type: application/json”

You can use the API to see the request with curl –insecure -H “Accept: $ACCEPT” -H “Authorization: $AUTH” https://$VRA/catalog-service/api/consumer/requests or access the UI.

18 Replies to “vRealize Automation REST API with Curl”

Nick on March 10, 2015 at 6:24 pm said:

Thanks for the info.. Great stuff. But on the path of continuous delivery, is there a way to get a callback method run using this API? So after the VM is up and running, I would then want to move forward and deploy a number of things.

Reply ↓
- Ryan Kelly on March 10, 2015 at 6:56 pm said:
  
  Hi Nick,
  
  Here is another guide I wrote for just that. You would need to modify the blueprint with a couple properties as well as add a script in the guest template. This is very similar to cloudinit but in vRA/vCAC we call it the Guest agent. It basically phones home to vRA/vCAC to run scripts in the guest after it boots up. You can add parameters as arguments to the script from the API when you request the VM from Jenkins. https://www.vmtocloud.com/how-to-call-vcac-vra-from-command-line-to-request-vms-and-run-scripts-in-the-guest/
  
  Also you may want to have a look at code stream that is much more out of the box for this. https://www.youtube.com/watch?v=2hGEoot9viU&index=1&list=PLrFo2o1FG9n7Pr4Fq-7exPvN6ThDYRcPV
  
  Reply ↓
  - Durga Prasad Mittal on May 18, 2015 at 10:51 am said:
    
    Hi Ryan,
    
    Thanks for the detailed help.
    I tried your steps and works like a charm.
    
    However i have issues executing “https://$VRA/catalog-service/api/consumer/entitledCatalogItems” using some REST console without using curl.
    I used the same token and end points which gives exact output in curl but throws the below error using some REST console :
    Error:
    HTTP Status 401 – Authentication required
    
    Any pointers would be really helpful.
    
    Thanks,
    Durga
    
    Reply ↓
    - Andy Knight on January 13, 2016 at 2:42 pm said:
      
      Durga,
      
      Did you get this resolved. I have exactly the same issue, everything works via curl but not via vRO REST interface or via a REST application (Firefox Restful plugin etc).
      
      Thanks
      
      Andy
      
      Reply ↓
Ariel on June 26, 2015 at 7:59 pm said:

Hi there, im using postman and I authnticate well but when I try to get catalog-service/api/consumer/entitledCatalogItems i receive an empty response:

{
“links”: [],
“content”: [],
“metadata”: {
“size”: 20,
“totalElements”: 0,
“totalPages”: 0,
“number”: 1,
“offset”: 0
}
}

any ideas?

Reply ↓
- Dan on January 4, 2016 at 8:18 pm said:
  
  Ariel, I’m having the same issue. Did you find the fix for it?
  
  Reply ↓
  - Ariel on May 30, 2016 at 8:05 pm said:
    
    Yeap, it was a typo on tenant name.
    
    Reply ↓
    - shivendra singh on December 8, 2016 at 12:42 pm said:
      
      Ariel, i am also getting the same issue. i have no typo mistake on tenant name.
      still getting the same empty response.
      
      {
      “links”: [],
      “content”: [],
      “metadata”: {
      “size”: 20,
      “totalElements”: 0,
      “totalPages”: 0,
      “number”: 1,
      “offset”: 0
      }
      }
      
      Reply ↓
http://www.themindstylecompany.com/ on May 1, 2016 at 1:11 am said:

ha! this totally sounds like you! love you!oh the times i’ve been by myself with the kids unable to get the stupid stroller to collapse, or once collapsed, to fit it into the trunk (esp. the doubles!)!

Reply ↓
john on May 7, 2016 at 6:27 am said:

How can you export the contents into a delimited csv file. For example if I only wanted “key” and “value”

Reply ↓
Omri Spector on May 11, 2016 at 3:04 pm said:

Where do I get the provider-blueprintId and provider-provisioningGroupId values?
They are not returned in the body of the previous consumer/entitledCatalogItems request

Reply ↓
http://www.tributetowayne.com/ on May 27, 2016 at 4:05 pm said:

LOL, you guys … Time is definitely investment and time is the critical component to generating a backlist of novels or even stories. The trick is deciding whether to have patience and develop your own backlist or to just simply begin and see where it leads you. Congrats on your success, Brand and thanks for the comment

Reply ↓
http://pilulesenligne.men/ on August 9, 2016 at 11:11 am said:

Hello. Very cool website!! Guy .. Excellent .. Wonderful .. I’ll bookmark your site and take the feeds also…I’m happy to locate numerous helpful information here in the post. Thank you for sharing.

Reply ↓
Kamal Tiwari on January 15, 2018 at 1:09 pm said:

how to sent the resource id collection to get the resources properties by using the rest API “/api/resources/properties”. i using the this api via postman but its throwing error not able to convert resourceid

Reply ↓
- Kamal Tiwari on January 15, 2018 at 1:11 pm said:
  
  how to send resource id array in get method
  
  Reply ↓
mars4life on March 2, 2018 at 10:28 am said:

How can i use the API to follow the status of a request ?
https://$VRA/catalog-service/api/consumer/requests seems the answer but, i already have more than 600 requests , and i only want the last one.
or may be i can catch the id of my request and directly ask for his status ?

Reply ↓
- mars4life on March 2, 2018 at 10:44 am said:
  
  i’ve found the simpliest way: catch the RequestId in the response of the initial request and then simply hit https://$VRA/catalog-service/api/consumer/requests/$RequestId
  
  But if somebody have a way to have the list of requests with the status “FAILED” from the last 24h for example, it will be helpfull
  
  Reply ↓
minecraft on September 9, 2018 at 6:02 am said:

May I simply just say what a comfort to uncover an individual who actually knows what they are talking about
on the web. You actually understand how to bring an issue to light and make it important.
More and more people need to look at this and understand
this side of the story. I can’t believe you are not more popular because you definitely have the gift.

Reply ↓