REST API

Cheatsheet for the entire VMware AppCatalyst API using cURL

01/22/2016 by William Lam 1 Comment

There were a few questions recently about the required syntax for specific VMware AppCatalyst operations when consuming the REST API using cURL. I figured I put together a quick "cheatsheet" that contains cuRL examples for the entire VMware AppCatalyst API which not only would it help me in future but could also benefit others. Like many, I also learn by example and having explicit samples to start with is a great way to get familiar with a new technology or product. If you are new to VMware AppCatalyst and would like a quick run down on how to quickly get started, be sure to check out my getting started article here for more details.

While going through the AppCatalyst API, I did find a couple of API operations which had some inconsistencies and did not strictly adhere to the JSON format. Thanks to Roman Tarnvski for providing the solution. I am hopeful that these issues will be resolved in a future update of AppCatalyst as I do like the ease of use of their API. For the majority of the API, the self documentation via the AppCatalyst API Explorer is accurate, which you can see from the screenshot below.

Before you can interact with the AppCatalyst REST API, you will need to start the AppCatalyst Daemon by running the following command:

/opt/vmware/appcatalyst/bin/appcatalyst-daemon

Once the AppCatalyst Daemon is running, you can open a new terminal and start working with the REST API via cURL or any other tool of choice.

1. Create a new VM from the default Photon OS VM template:

You technically only need to specify the unique "id" property, but you can also give a display name for the VM by using the "name" property.

curl -d '{"id":"VM1", "name":"MyAppCat-VM1"}' -X POST localhost:8080/api/vms

2. Clone a VM from an existing VM:

Similar to creating a new VM, you also have option of using the "tag" property to associate additional metadata with the VM.

curl -d '{"id":"VM2", "parentid":"VM1", "name":"MyAppCat-VM2", "tag":"Development"}' -X POST localhost:8080/api/vms

3. List all VMs

curl -X GET localhost:8080/api/vms

4. Get a specific VM:

To retrieve a specific VM, you will need to power on the VM before this operation is allowed. I did find it strange that this was the case, but perhaps this could be enhanced in the future to not have this requirement, especially if you want to pull out details such as the "tag" property.

curl -X GET localhost:8080/api/vms/VM1

5. Power On a VM:

curl -d 'on' -X PATCH localhost:8080/api/vms/power/VM1

Note: Other VM Power Operations: off, shutdown, suspend, pause & unpause

6. Get the power state of a VM:

curl -X GET localhost:8080/api/vms/power/VM1

7. Get the IP Address of a VM:

curl -X GET localhost:8080/api/vms/VM1/ipaddress

8. Enable folder sharing for a VM:

curl -d "true" -X PATCH localhost:8080/api/vms/VM1/folders

9. Create a shared folder mapping for a VM:

The "guestPath" property is not an absolute path within the guestOS, but rather a logical name. For more details about shared folders in AppCatalyst, please have a look at this article here. Currently there is only one "flags" property with the value of 4 which enables read/write, please refer to the article in the link above for more details about folder sharing in AppCatalyst.

curl -d '{"guestPath":"shared-folder","hostPath":"/Users/wlam/git","flags":4}' -X POST localhost:8080/api/vms/VM1/folders

10. List all shared folders to a VM:

curl -X GET localhost:8080/api/vms/VM1/folders

11. List a specific shared folder for a VM:

curl -X GET localhost:8080/api/vms/VM1/folders/shared-folder

12. Delete a shared folder for a VM:

curl -X DELETE localhost:8080/api/vms/VM1/folders/shared-folder

13. Delete VM:

curl -X DELETE localhost:8080/api/vms/VM1

Having some fun with the Marvel Comics API & vSphere SDK for Python

02/10/2014 by William Lam 2 Comments

As a child of the 80's, I still remember waking up super early on a Saturday morning to watch some of my favorite cartoons including Transformers, GI Joe, Ninja Turtles and many of the Marvel cartoon series. Last week I saw an interesting tweet from our former VMware CTO, Steve Herrod:

It looks like Marvel has just released a Marvel Comics REST API which allows developers to access the entire Marvel Comics Universe and build custom applications and websites with that data. So, you might be wondering what does this have to do with VMware and virtualization? Well, when I heard about this API, I knew I had to find a way to incorporate this into a cool VMware project.

I decided to create a sample vSphere SDK for Python (also known as pyvmomi) script that would allow a user to specify a number of random Marvel Characters to select from the Marvel database and then automatically create dummy VMs based on those names which could be used for testing. There were a variety of VMware SDK's (Perl, Ruby, PowerCLI, Java, etc) that I could have used, but I opted for the vSphere SDK for Python given my Python skills were not very strong. This also gave me a good reason to play around with our Python SDK.

There are a couple of things you will need to setup before you can use the sample script:

Setup a Marvel API key
Install vSphere SDK for Python, you can take a look here.
Download the create_random_marvel_vms.py

Disclaimer: There is not much error handling built into the sample script, please use at your own risk.

You will need to edit the script and replace the following two variables: marvel_public_key & marvel_private_key with the API key after creating an account on Marvel's website. One thing I really like about the Marvel API and I know many other vendors also provide this which is an interactive API tester. This allows a user to explore and execute a particular API requests without writing a single line of code to get a better understanding of the results before one starts to develop their application.

To run the script, you will need to pass in the following parameters:

--host : Name of your vCenter Server (only tested with vCenter)
--user : User to login with
--password : Password for the user
--datastore : Name of the datastore in which VMs will be created in
--count : The number of Dummy VMs to create

Here is an example of running the script:

./create_random_marvel_vms.py --host vcenter --user root --password vmware --datastore mini-local-datastore-1 --count 10

As you can see from the screenshot above I have just created 10 random VMs where each name is a random Marvel character extracted using a GET request on /v1/public/characters. If we head over to our vSphere Web Client, we should now see our 10 newly created VMs which contain 1vCPU and 128MB of memory. To keep things simple, I did not add a vDisk but you can easily tweak the dummy VM configuration based on your requirements.

Quick Tip – Automate the export of a vCenter Orchestrator workflow using the CLI

08/14/2013 by William Lam 5 Comments

Steve Jin recently wrote an article about vCenter Orchestrator REST APIs: Executing Workflow which reminded me of an interesting issue that I had faced several months back. I had just finished developing a custom workflow on a beta version of vCenter Orchestrator and of course one of the challenges with using early software is that it could be unstable. I was unable login to the vCO interface via vSphere Web Client or the vCO Client to export my workflow through the regular UI interface. I tried everything and I thought I might have lost my workflow!

I reached out to one of the vCO engineers and asked if there was an easy way to recover my workflow and it turns out there was a very simple method IF the vCO REST API endpoint is still accessible, which it was. To test this, you can either use cURL on the command-line or your favorite REST Client for your browser and perform a GET operation on the following URL (replace the URL with the URL of your vCO Server):

https://vco.primp-industries.com:8281/api/workflows

Note: The vCO REST API is only available starting with vSphere 5.1

If the command was successful, you should see a list of all the workflows in your vCO Server:

I am not aware of any filtering that can be done to narrow down the specific vCO Workflow, but if you are using a browser-based REST Client, you can just search for the name of your workflow. In the above example, I am interested in the "Change Guest OS Type" workflow and you can see its corresponding vCO Workflow ID which is highlighted.

To export and save the vCO Workflow to your local system, you just need to perform a GET operation on the vCO Workflow URL and specify "Accept:application/zip" for the request header which will allow you to save the vCO workflow.

Here is an example using cURL to export the vCO Workflow and save to a file called ChangeGuestOS.workflow:

curl -i -k -u vcoadmin -H "Accept:application/zip" -X GET https://vco.primp-industries.com:8281/api/workflows/7D808080808080808080808080808080BC818080013141141566711a974a8fef8 -o ChangeGuestOS.workflow

Exploring the vCloud Networking & Security API Using Ruby

02/25/2013 by William Lam 2 Comments

In my previous article I demonstrated how you can easily use Ruby and the HTTParty Gem to access the vCloud API. As mentioned at the end of the article I also performed a similar exercise for the vCloud Networking and Security API and here is the sample Ruby script I reated called vcns.rb.

Before getting started, you will need to have the following installed on your system:

ruby (I used the latest release which is 1.9.3)
ruby gem
httparty
libxml
yaml

You will also need to access to a vCloud Networking and Security 5.x environment to use this script. To begin, create a file called config-vcns.yml which contains the credentials to your vCNS system and will be used to login. Here is what the file should look like the following:

:username: admin
:password: default
:site: https://vcns.primp-industries.com

The script provides the following output:

vCNS Configuration
vCNS Edge Gateway(s) Details
Syslog Service Details
HA Service Details
Firewall Service Details
DNS Service Details
SSL-VPN Service Details
IPSec Service Details
DHCP Service Details
NAT Service Details
Load Balancer Service Details

Here is a screenshot of running the vcns.rb script:

As you can see, you can easily implement any of the features provide from the vCloud Networking and Security API, with some basic knowledge of how the API works (of course the documentation examples help too!). To further demonstrate this, I thought for kicks and giggles, I would take a part of the script and apply it to another language, this time using PowerShell (yep, you heard right!).

Luckily, it turns out my colleague Alan Renouf already wrote an awesome little PowerShell module for vShield (vCNS) awhile back. With some knowledge of the vCNS API, it was trivial to add a new command called get-vShieldEdge which Alan did not have that would list all the vCNS Edge Gateways that have been deployed.

Here is what the the code looks like in Ruby:

Here is what the code looks like for PowerShell:
Minus the language syntax, it looks pretty similar right? Both Ruby and PowerShell are accessing the same vCNS API. As long as you know how the API works, it is pretty easy to switch between programming/scripting languages.

To show the above code works, here is screenshot using the new get-vShieldEdge command:

If you are interested in further automation of vCNS, I would highly recommend you take a look at the vCloud Networking and Security API Programming Guide.

Useful Resources:

http://blogs.vmware.com/security/2011/11/using-the-vshield-api.html

Exploring the vCloud API Using Ruby

02/21/2013 by William Lam 2 Comments

While working on something that was completely random, I started to play around a bit with the Ruby programming language. I had a few questions and I reached out to a buddy of mine who is Ruby developer and in doing so I was introduced to a very cool Ruby gem called HTTParty. For those of you who are not familiar with Ruby gems, it is a packaged library or application for Ruby, similar to an rpm or pkg file. The neat thing about HTTParty is that it makes working with REST APIs extremely easy and processing XML request/responses into Ruby objects without too much effort.

With the bit of knowledge I gained from my buddy, I wanted to see how easy it would be to apply this to the vCloud API using Ruby and HTTParty. To my surprise, it was actually pretty easy!

Disclaimer: I am not a developer nor even a Ruby novice. This is probably the second or third time I have used Ruby.

Before getting started, you will need to have the following installed on your system:

ruby (I used the latest release which is 1.9.3)
ruby gem
httparty
xml-fu
yaml

The following vCloud APIs are implemented in the sample below:

To demonstrate the use of Ruby & HTTParty, I created a very simple Ruby script called vcd.rb which primarily deals with vApp operations.

To use the script, you will need to create a file called config-vcd.yml which contains the credentials to your vCloud Director instance. Here is what the file should look like:

:username: [email protected]
:password: supersecretpassword
:site: https://vcd.primp-industries.com

Note: This example assumes you are running vCloud Director 5.1 (but sample can be modified to support 1.5)

Here is an example of listing all vApps for the given Organization you are logging into:

Here is an example of listing a specific vApp:

Here is an example of performing several operations on the vApp:

At the end of this little exercise, I was pretty impressed at how easy it was to work with REST APIs using Ruby and HTTParty. I think the toughest part for me personally was getting used to Ruby's syntax which I was not familiar with. I also extended this exercise to the vCloud Networking and Security REST APIs which I will share in another blog post.

Useful Resources:

Nested Virtualization APIs For vSphere & vCloud Director 5.1

10/18/2012 by William Lam 2 Comments

Did you know with the release of vSphere 5.1 and vCloud Director 5.1, there are now APIs that allow you to enable/disable Nested Virtualization aka (Virtual Hardware Virtualization) on a Virtual Machine?

Disclaimer: Nested Virtualization is not officially supported by VMware.

In the vSphere 5.1 API, there are two new properties related to Nested Virtualization:

nestedHVSupported is a new capability property which indicates whether your physical ESXi 5.1 host supports Nested Virtualization. This property is only true IF your physical CPU supports BOTH Intel-VT/EPT OR AMD-V/RVI. For more details, please refer to this article.
nestedHVEnabled is new property on a Virtual Machine which allows you to enable or disable Nested Virtualization. You will need to ensure you are running a Virtual Machine with ESXi 5.1 Compatibility (e.g. virtual hardware 9) and your physical ESXi 5.1 host supports Nested Virtualization.

Here is a screenshot of performing the same operation manually using the new vSphere Web Client:

In the vCloud Director 5.1 REST API, there two new operations related to Nested Virtualization:

/action/enableNestedHypervisor is a new operation on a Virtual Machine that enables Nested Virtualization. Here is an example using the curl utility enable VHV:
curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: xX4IrWWi+Ofq77zOqPJaMEYHHJt4jxrwP+ntkO2tecQ=" -X POST https://vcd.primp-industries.com/api/vApp/vm-d9870545-a29a-4175-bff4-ae075f1c1bc0/action/enableNestedHypervisor
/action/disableNestedHypervisor is a new operation on a Virtual Machine that disables Nested Virtualization. Here is an example using the curl utility to disable VHV:
curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: xX4IrWWi+Ofq77zOqPJaMEYHHJt4jxrwP+ntkO2tecQ=" -X POST https://vcd.primp-industries.com/api/vApp/vm-d9870545-a29a-4175-bff4-ae075f1c1bc0/action/disableNestedHypervisor

Here is a screenshot of performing the same operation manually using the vCloud Director UI:

If you plan to leverage Nested Virtualization in your environment, you now have simple way of automating this feature for Virtual Machines that you wish to support Nested Virtualization.