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
thx! one liner direct ssh login (could be extended by providing the VM name as a $variable): ssh -i /opt/vmware/appcatalyst/etc/appcatalyst_insecure_ssh_key photon@$(curl -s localhost:8080/api/vms/test_api/ipaddress| cut -d"\"" -f 6)