VMware App Volumes API Reference

**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

Screen Shot 2015-12-29 at 9.50.05 AMWhen 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.

Screen Shot 2015-12-29 at 9.52.51 AM

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

Screen Shot 2015-12-29 at 9.44.33 AM

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.

Screen Shot 2015-12-28 at 8.28.21 AM

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.

Screen Shot 2015-12-28 at 8.28.33 AM.png

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.

Screen Shot 2015-12-30 at 8.56.25 AM

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.

Screen Shot 2015-12-30 at 9.07.52 AM

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

Screen Shot 2015-12-30 at 9.10.41 AM

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.

Screen Shot 2015-12-30 at 9.24.44 AM

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

Screen Shot 2015-12-28 at 8.47.08 AM

Get App Volumes License Information:

Verb: Get

URL: http:///cv_api/license

Screen Shot 2015-12-28 at 8.50.42 AM

Get App Volumes License Usage Information:

Verb: Get

URL: http:///cv_api/license_usage

Screen Shot 2015-12-28 at 8.54.31 AM

Get Active Directory Settings:

Verb: Get

URL: http:///cv_api/ad_settings

Screen Shot 2015-12-28 at 9.54.39 AM

Get Current Administrator Group for the App Volumes Manager:

Verb: Get

URL: http:///cv_api/administrator

Screen Shot 2015-12-28 at 9.57.50 AM

Get Machine Managers:

Verb: Get

URL: http:///cv_api/machine_managers

Screen Shot 2015-12-28 at 10.02.05 AM

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

Screen Shot 2015-12-28 at 10.42.42 AM

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

Screen Shot 2015-12-28 at 10.46.21 AM

AppStack / Writable Volume API Calls

Get a list of AppStacks:

Verb: Get

URL: http:///cv_api/appstacks

Screen Shot 2015-12-28 at 10.51.40 AM

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

Screen Shot 2015-12-28 at 10.54.40 AM

Get applications installed in an AppStack:

Verb: Get

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

Screen Shot 2015-12-28 at 10.59.18 AM
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

Screen Shot 2015-12-28 at 11.03.49 AM

Get current assignments for an AppStack:

Verb: Get

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

Screen Shot 2015-12-28 at 11.06.50 AM

Get current attachments for an AppStack:

Verb: Get

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

Screen Shot 2015-12-28 at 11.07.00 AM

List Writable Volumes:

Verb: Get

URL: http:///cv_api/writables

Screen Shot 2015-12-28 at 11.13.20 AM
Get detailed information for a Writable Volume:

Verb: Get

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

Screen Shot 2015-12-28 at 11.15.11 AM

Disable Writable Volume:

Verb: Post

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

Screen Shot 2015-12-29 at 5.53.28 PM

Enable Writable Volume:

Verb: Post

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

Screen Shot 2015-12-29 at 5.50.57 PM
Get Current Attachments:

Verb: Get

URL: http:///cv_api/attachments

Screen Shot 2015-12-29 at 4.50.26 PM

Get Current Assignments:

Verb: Get

URL: http:///cv_api/assignments

 Screen Shot 2015-12-29 at 4.52.26 PM

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=

Screen Shot 2015-12-29 at 5.58.25 PM

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=

Screen Shot 2015-12-29 at 6.11.20 PM

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=

Screen Shot 2015-12-29 at 6.17.25 PM

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

Verb: Get

URL: http:///cv_api/applications

Screen Shot 2015-12-29 at 4.54.16 PM
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

Screen Shot 2015-12-29 at 4.56.18 PM

 App Volumes Directory API Calls

Get a list of all online entities:

Verb: Get

URL: http:///cv_api/online_entities

Screen Shot 2015-12-29 at 5.01.42 PM

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

Screen Shot 2015-12-29 at 5.03.32 PM

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

Verb: Get

URL: http:///cv_api/computers

Screen Shot 2015-12-30 at 10.28.24 AM

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

Verb: Get

URL: http:///cv_api/groups

Screen Shot 2015-12-29 at 5.07.43 PM

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

Verb: Get

URL: http:///cv_api/org_units

Screen Shot 2015-12-29 at 5.11.03 PM

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

Screen Shot 2015-12-30 at 10.33.45 AM

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

Verb: Get

URL: http:///cv_api/storages

Screen Shot 2015-12-30 at 10.35.20 AM

Get a list of all Storage Groups:

Verb: Get

URL: http:///cv_api/storage_groups

Screen Shot 2015-12-30 at 10.36.45 AM

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

Screen Shot 2015-12-30 at 10.37.38 AM

Force Replication for a Storage Group:

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

Screen Shot 2015-12-30 at 10.38.47 AM 
Import Volumes into a Storage Group:

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

Screen Shot 2015-12-30 at 10.40.00 AM.png
App Volumes Activity API Calls

Show Pending Actions:

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

Screen Shot 2015-12-30 at 10.41.23 AM.png

Return Activity Log:

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

Screen Shot 2015-12-30 at 10.42.15 AM.png

Show System Messages:

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

Screen Shot 2015-12-30 at 10.43.24 AM
Show Server Logs from App Volumes Manager:

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

Screen Shot 2015-12-30 at 10.44.39 AM.png

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

Advertisements
This entry was posted in App Volumes, Coding. Bookmark the permalink.

7 Responses to VMware App Volumes API Reference

  1. Pingback: App Volumes automated install | myEUC.net

  2. Michael Ansich says:

    Well done.

    Will there be a document that will reference all API methods?

  3. Justin says:

    Chris, I think there’s a typo with your, “Assign an AppStack to a User, Group or OU,” example. I think you accidentally used the url for computer based assignments. Shouldn’t the example be something like this:

    http:///cv_api/assignments?action_type=Assign&id=1&assignments%5B0%5D%5Bentity_type%5D=User&assignments%5B0%5D%5Bpath%5D=CN%3Dbrady%2COU%3DUsers%2CDC%3Dhalstead%2CDC%3Dnet&rtime=false&mount_prefix=

    Unfortunately, I can’t seem to get the syntax right in my own environment. Keep getting the message below when trying at assign app stacks to a user. The computer based assignment seems to work.

    {
    “warning”: “All entities were already Assigned”
    }

    I’m absolutely thrilled with this blog entry by the way. This is awesome!

  4. gpeck29 says:

    Is there an API Call to SET ad_settings? Specifically, I’m looking to update the Trust_Domains with a string longer than the UI can accept. We have 4 domains that I want to update all of which I want to specify a domain controller address. Doing this in the UI is impossible as the UI won’t take the number of characters I need to input.

    • gpeck29 says:

      I confirmed in AppVolumes 2.9 the Trust Domains input is set to a max length of 100. I need 135 characters. Wondering if there is a reason for the 100 on the backend or if it was an arbitrary setting chosen during the UI configuration. It appears that all fields are set to maxlength=”100″.

      • I am not sure why the 100 character limit, but yes you can update that setting via API. Here is the information:

        Verb: POST
        URL: https://avmanager/cv_api/ad_settings?connectcheck=1

        Parameters:
        base – LDAP Base (optional)
        domain – Primary Domain
        host – Optional Domain Controller
        password – password for Primary Domain
        trust_domains – list of the trust domains – separated by semi-colon
        trust_password – password to access trust domains
        trust_username- username to access trust domains
        username – username for primary domain

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s