**NOTE:  The App Volumes API is NOT Officially Supported by VMware**

VMware App Volumes has a fully featured REST API that can be used to automate any function that can be done from within the App Volumes manager. A REST API uses the standard HTTP protocol and Verbs to retrieve or set data.

The input parameters, which are posted to the REST API and the data returned are formatted as JSON.   Note: A user must be defined as an App Volumes Administrator in order to use the API

In order to set and retrieve data to the API you need to have a client, which is capable of sending and retrieving data using HTTP / URL syntax.   There are many that are available for free. I will focus on cURL and Postman in this article.  I have also written a few applications in VB.net using the App Volumes API.  I will post some sample code for .NET in a future post.   The API wasn’t really documented so I decided to put this post together to help others who may want to program against the API.

Clients for REST API

As mentioned, there are several ways to connect and retrieve data from the App Volumes API.   Here are a couple of the most popular:

cURL

cURL is a command line data transfer utility for protocols using the URL syntax.     It can be downloaded for free for most operating systems. I will provide some sample syntax for cURL in the next section.

Google Postman

Google offers an add-on for the Chrome browser called Postman. This is the client I prefer for quickly checking the API syntax and returning data. It is easy to use, and returns the nicely formatted JSON data.   Postman can be easily added to any instance of the chrome browser and accessed from the Chrome App Launcher. You will also need to install the Postman Interceptor extension for Postman to be able to read and save browser-based cookies, which is where the session for the API connection will be saved.

Connecting to the App Volumes API

We will now use the Postman REST API and cURL clients to connect to App Volumes and create a session.   App Volumes stores the session data in a cookie.  Once we have that session cookie, we can reference it to pull other data from the API. We can log in one time, and as long as our session doesn’t time out, we can continue to use the API.

cURL

With cURL we will establish a connection to the API and save the session cookie to a text file. We can then reference the cookie text file when we want to do additional actions against the API

Login to API and save the session Cookie:

curl -c cookies.txt -H “Content-Type: application/json” -X POST -d ‘{“username”:”avuser”,”password”:”password”}’ http://192.168.1.25/cv_api/sessions

When you successfully log into the API you will receive the following JSON message:

{“success”:”Ok”}

If you look at the cookie file that is created, we can see that it contains a _session_id value. This is the session cookie.

We can now run additional commands and reference the cookie we saved:

Return Writable Volumes and format the JSON to make it easier to read. Notice we are referencing the cookies.txt file we created when we logged in. Note: The | python –m json.tool is optional and just helps format the returned JSON data to make it easier to read.

curl -b cookies.txt -H “Content-Type: application/json” -X GET http://192.168.1.25/cv_api/writables | python -m json.tool

Google Postman

• Launch the Postman client do the following to create a session:
  • Make sure that the Postman Interceptor add in is installed to handle cookies
  • Make sure the Verb is set to POST
  • Type http://<app_volumes manager>/cv_api/sessions in the address bar
  • Click Body, select form-data
    • Enter a Key called username with the username of an App Volumes Administrator
    • Enter a Key called password with the password associated with this account
    • Hit Send to make the connection – if successfully authenticated you will see   “success”: “Ok” in the return data of the body.

You have successfully authenticated to the App Volumes API.   If you click the cookies tab, you will notice you have been issued a session cookie. This will be passed back to the App Volumes manager API each time you attempt to connect. As long as the session is still valid, you won’t be prompted for Authentication.

If your session times out, you will receive a message similar to the one below, just post back to the API to establish another session as we did earlier.

Issues Logging In

You may receive the following error messages when attempting to log in to the App Volumes API:

Invalid username or password – make sure the username (domain\username) and the password are correct and try again.

You must be in the Administrators group to Login

If you receive the message below, the account that you are attempting to log in with is not a member of the group defined as App Volumes Administrators

You can check what group is defined as the App Volumes Administrators group by logging into the App Volumes Manager and browsing to “Configuration” | “Administrators”. Make sure the account you are using to access the API is a member of this group and try connecting again.

Let’s start using the App Volumes API. I will break out the API calls as they are arranged in the App Volumes manager today. The same URL paths and verbs will work for either Postman or cURL. I will be using Postman in my examples as I find it easier to use.

General App Volumes API Calls

In this section we will cover API commands to retrieve general data from App Volumes.

Get App Volumes Version Information:

Verb: Get

URL: http:///cv_api/version

Get App Volumes License Information:

Verb: Get

URL: http:///cv_api/license

Get App Volumes License Usage Information:

Verb: Get

URL: http:///cv_api/license_usage

Get Active Directory Settings:

Verb: Get

URL: http:///cv_api/ad_settings

Get Current Administrator Group for the App Volumes Manager:

Verb: Get

URL: http:///cv_api/administrator

Get Machine Managers:

Verb: Get

URL: http:///cv_api/machine_managers

Get Machine Manager Detailed Configuration:
You will need to note the “id” of the machine manager you want to return more information for.

Verb: Get

URL: http:///cv_api/machine_managers/id

Get Storage Options:
This will show the paths of where the AppStacks, Writables and Templates are stored and some basic information on the datastores.

Verb: Get

URL: http:///cv_api/datastores

AppStack / Writable Volume API Calls

Get a list of AppStacks:

Verb: Get

URL: http:///cv_api/appstacks

Get detailed AppStack Information:
You will need to note the “id” of the AppStack you want to return additional data for.

Verb: Get

URL: http:///cv_api/appstacks/id

Get applications installed in an AppStack:

Verb: Get

URL: http:///cv_api/appstacks//applications

Get file locations for an AppStack:
This will show all of the data store locations for an AppStack if you are using a Storage Group.

Verb: Get

URL: http://<App_Volumes_Manager/cv_api/appstacks/id/files

Get current assignments for an AppStack:

Verb: Get

URL: http:///cv_api/appstacks/id/assignments

Get current attachments for an AppStack:

Verb: Get

URL: http:///cv_api/appstacks/id/attachments

List Writable Volumes:

Verb: Get

URL: http:///cv_api/writables

Get detailed information for a Writable Volume:

Verb: Get

URL: http:///cv_api/writables/id 

Disable Writable Volume:

Verb: Post

URL:
http:///cv_api/writables/disable?volumes%5B%5D=id

Enable Writable Volume:

Verb: Post

URL:
http:///cv_api/writables/enable?volumes%5B%5D=id

Get Current Attachments:

Verb: Get

URL: http:///cv_api/attachments

Get Current Assignments:

Verb: Get

URL: http:///cv_api/assignments

 

Assign an AppStack to a Computer:

Verb: Post

Parameters:

action_type=Assign

id=1 (this is the AppStack ID)

assignments[0][entity_type]= Computer

assignments[0][path]=CN=HOMEWIN7,CN=Computers,DC=halstead,DC=net

mount_prefix=(optional parameter)

rtime= false (true mount immediately, false mount at next login)

URL: http:///cv_api/assignments?action_type=Assign&id=1&assignments%5B0%5D%5Bentity_type%5D=Computer&assignments%5B0%5D%5Bpath%5D=CN%3DHOMEWIN7%2CCN%3DComputers%2CDC%3Dhalstead%2CDC%3Dnet&rtime=false&mount_prefix=

Assign an AppStack to a User, Group or OU:

Verb: Post

Parameters:

action_type=Assign

id=1 (this is the AppStack ID)

assignments[0][entity_type]= User

assignments[0][path]=CN=Brady,OU=Home_Users,DC=halstead,DC=net

mount_prefix=(optional parameter)

rtime= true (true mount immediately, false mount at next login)

URL: http:///cv_api/assignments?action_type=Assign&id=1&assignments%5B0%5D%5Bentity_type%5D=Computer&assignments%5B0%5D%5Bpath%5D=CN%3DHOMEWIN7%2CCN%3DComputers%2CDC%3Dhalstead%2CDC%3Dnet&rtime=false&mount_prefix=

Unassign an AppStack:

Verb: Post

Parameters:

action_type=Unassign

id=1 (this is the AppStack ID)

assignments[0][entity_type]= User or Computer

assignments[0][path]=CN=Brady,OU=Home_Users,DC=halstead,DC=net

mount_prefix=(optional parameter)

rtime= true (true mount immediately, false mount at next login)

URL: http:///cv_api/action_type=Unassign&id=1&assignments%5B0%5D%5Bentity_type%5D=User&assignments%5B0%5D%5Bpath%5D=CN%3DBrady

%2COU%3DHome_Users%2CDC%3Dhalstead%2CDC%3Dnet&assignments%5B0%5D%5Bid%5D=2&rtime=true&mount_prefix=

Get a list of all applications contained in all defined AppStacks:

Verb: Get

URL: http:///cv_api/applications

Get detailed information on an Application:
You will need to note the “id” of the Application you want more data on.

Verb: Get

URL: http:///cv_api/applications/id

 App Volumes Directory API Calls

Get a list of all online entities:

Verb: Get

URL: http:///cv_api/online_entities

Get a list of all users who have logged into a managed computer or have had a volume assigned to them:

Verb: Get

URL: http:///cv_api/users

Get a list of all computers that have reported with an App Volumes Agent:

Verb: Get

URL: http:///cv_api/computers

Get a list of all groups that have been assigned an AppStack

Verb: Get

URL: http:///cv_api/groups

Get a list of all AD OUs that have been assigned an AppStack:

Verb: Get

URL: http:///cv_api/org_units

App Volumes Infrastructure API Calls

Get a list of all machines that have been seen by this App Volumes Manager:

Verb: Get

URL: http:///cv_api/machines

Get a list of all storage locations seen by this App Volumes Manager:

Verb: Get

URL: http:///cv_api/storages

Get a list of all Storage Groups:

Verb: Get

URL: http:///cv_api/storage_groups

Get detailed information for a Storage Group:
You will need to note the “id” of the Storage Group you want more data for.

Verb: Get
URL: http:///cv_api/storage_groups/id

Force Replication for a Storage Group:

Verb: Post
URL: http:///cv_api/storage_groups/id/replicate

 
Import Volumes into a Storage Group:

Verb: Post
URL: http:///cv_api/storage_groups/id/import

App Volumes Activity API Calls

Show Pending Actions:

Verb: Get
URL: http:///cv_api/pending_activities

Return Activity Log:

Verb: Get
URL: http:///cv_api/activity_logs

Show System Messages:

Verb: Get
URL: http:///cv_api/system_messages

Show Server Logs from App Volumes Manager:

Verb: Get
URL: http:/// activity/server_tail

Hopefully this post was helpful in understanding how the App Volumes API is constructed.  Please let me know if you have any questions.

Additional API Calls

Create an AppStack:

Verb – POST

URL – https://cv_api/appstacks

Parameters:

bg	1
datacenter	Home
datastore	SSD1|Home|1
description
name	NewAppstack
parent_appstack_id
path	cloudvolumes211/apps
template_name	template.vmdk
template_path	cloudvolumes211/apps_templates

Watch the Job process:

Verb – GET 

URL – https://cv_api/jobs/pending

Make sure the job is complete

{

  “pending”: 0,

  “error”: 0

}

Get ID of the AppStack that was just created.

Verb – GET

URL – https://cv_api/appstacks

{

    “id”: 8,

    “name”: “NewAppstack”,

    “name_html”: “NewAppstack”,

    “path”: “cloudvolumes211/apps”,

    “datastore_name”: “SSD1”,

    “status”: “provisioning”,

    “created_at”: “2016-05-13 08:41:38 -0400”,

    “created_at_human”: “May 13 2016”,

    “mounted_at”: “2016-05-13 08:45:53 -0400”,

    “mounted_at_human”: “May 13 2016”,

    “mount_count”: 0,

    “size_mb”: null,

    “template_version”: null,

    “assignments_total”: 0,

    “attachments_total”: 1

  },

Query Desktops capable of provisioning and choose a system:

Verb – GET

URL – https://cv_api/provisioners

Make sure system is Available and capture the uuid and computer id:

{

  “provisioners”: [

    {

      “upn”: “HALSTEAD\\AV211-IC-2$”,

      “status”: “Available”,

      “id”: “6”,

      “name”: “HALSTEAD\\AV211-IC-2$”,

      “link”: “/directory#/Computers/6”,

      “uuid”: “5009e3d5-7d59-da85-eeab-4ffe2d31e40a”,

      “selectable”: true,

      “created_at”: “2016-05-07 22:38:09 UTC”,

      “created_at_human”: “May 07 2016”

    },

    {

      “upn”: “HALSTEAD\\H7-MASTER$”,

      “status”: “Powered Off”,

      “id”: “1”,

      “name”: “HALSTEAD\\H7-MASTER$”,

      “link”: “/directory#/Computers/1”,

      “uuid”: “50097949-d73d-0804-2bcb-18cc9b23c541”,

      “selectable”: false,

      “created_at”: “2016-05-07 13:40:10 UTC”,

      “created_at_human”: “May 07 2016”

    },

Start Provisioning:

Verb – POST

URL – https://cv_api/provisions/start

Parameters:

computer_id	6
uuid	5009e3d5-7d59-da85-eeab-4ffe2d31e40a

*Install Applications on Provisioning System*

Finish Provisioning:

Verb – POST

URL – https://cv_api/provisions/complete

Cancel Provisioning:

POST to:  https://cv_api/provisions/stop