Introduction

By sending requests to the Virtual Machine endpoint /v2/vm you can list, create, update or delete VMs. The Virtual Machine endpoint has the following methods available:

Resource	URI	Description	GET	POST	PUT	DELETE
Virtual Machine	/vm	Virtual Machine management resource. Read, update, delete, create virtual machines.

Note

title	OPTIONS HTTP method

Remember, you can also show what methods are allowed and method description, parameters, etc. by making a GET HTTP request to /v2/vm.

Code Block

language	bash

http OPTIONS "https://vss-api.eis.utoronto.ca/v2/vm"
curl -X OPTIONS "https://vss-api.eis.utoronto.ca/v2/vm"

Panel

On this page:

Table of Contents

outline	true

Create

Single Virtual Machine

To create a new Virtual Machine, send a POST request to /v2/vm. The attribute values that must be set to successfully create a Virtual Machine are marked with a in the following table:

Attribute	Description	Type	Ref URI	Options	Default	Required
admin_email	Administrator's email	string	-	-	User's email number submitting the request	-
admin_name	Administrator's name	string	-	-	User's name number submitting the request	-
admin_phone	Administrator's phone number	string	-	-	User's phone number submitting the request	-
bill_dept	Billing Department	string	-	-	-
built_from	Build process. If you are installing OS from scratch use os_install. Clone when deploying a VM from a running or powered off virtual Machine. Template gives the ability to deploy multiple VMs at the same time.	string	-	os_install clone template image	-
cpu	CPU count	integer	-	-	1	-
description	Short description of the service or application. This will be part of the annotations field.	string	-	-	-
disks	Disks in GigaBytes.	array	-	-	[40]	-
high_io	If set to true,VM will be created with a VMware Paravirtual SCSIController. PVSCSI controllers are best suited for environments, especially SAN environments, running I/O-intensive applications.	boolean	-	True False	False	-
domain	Fault domain moId (Managed Object Identifier)	string	/v2/domain	-	Fault Domain 3	-
folder	Folder moId (Managed Object Identifier)	string	/v2/folder	-	-
inform	Informational comma separated emails or list of email addresses.	string or list of strings	-	-	User's email submitting the request	-
iso	ISO image path to be mounted after creation	string	/v2/iso	-	None	-
memory	Memory in GB	integer	-	-	1	-
name	Human readable name without the VSS Prefix. This prefix will be added before creation.	string	-	-	Randomly generated	-
networks	Network Managed Object Identifier (moId) array. Each network will be attached to a Network Adapter VMXNET3, the most recent virtual network device from VMware, and was designed from scratch for high performance and to support new features.	array	/v2/network	-	Unaccessible VLAN	-
os	Supported guest operating system identifier.	string	/v2/os	-	-
usage	Virtual Machine usage. Prod for Production, Test for testing, QA for Quality Assurance, and Dev for Development.	string	-	Prod Test QA Dev	Test	-
notes	Client notes to be stored in the annotation field.	string	-	-	-	-
source_vm	Source Virtual Machine Uuid.	string	/v2/vm	-	-	only with clone
source_template	Source Virtual Machine Template Uuid.	string	/v2/template	-	-	only with template
source_image	Source OVA/OVF Virtual Machine file stored in VSKEY-STOR	string	/v2/image	-	-	only with image
user_data	Cloud-init user_data to preconfigure the guest os upon first boot. Note: Experimental feature and currently tested with Ubuntu Cloud Images and VMware Photon OS. Only supported on OVA/OVF deployments.	string	-	-	-	-
extra_config	Allows to Set *VMware guestinfo* interface properties which are available to the VM guest operating system via VMware Tools. These properties are stored in the VMX file prefixed with "guestinfo."**.	dict	-	-	-	-
custom_spec	Customize a guest operating system to prevent conflicts if virtual machines are identical after deployed. To customize the guest operating system, you must configure the virtual machine and guest to meet VMware Tools and virtual disk requirements.	dict	-	-	-	recommended with clone and template deployment
ha_group	Create high availability UUID group metadata.	array or string	/v2/vm	-	-	-
vss_options	Sets available VSS Options to virtual machine metadata.	array or string	/v2/vss/options	-	-	-
vss_service	Tags Virtual Machine with a specific predefined service.	string	/v2/vss/service	-	-	only for ITS users

A new virtual machine can be created with as few as the following attributes in JSON format:

Code Block

language	py
title	Request Body

{"usage": "Prod",
 "os": "ubuntu64Guest",
 "built_from": "os_install",
 "bill_dept": "EIS",
 "description": "Java web application.",
 "folder": "group-v4122",
 "networks": ["dvportgroup-95",
              "dvportgroup-92"],
 "disks": [40, 100]
}

HTTPie

Code Block

http POST "https://vss-api.eis.utoronto.ca/v2/vm" "Authorization: Bearer $TK" usage='Prod' os='ubuntu64Guest' built_from='os_install' bill_dept='EIS' description='Java web application.' folder='group-v4122' networks:='["dvportgroup-95", "dvportgroup-92"]' disks:='[40, 20]'

CURL

Code Block

curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm" -d '{"usage": "Prod", "os": "ubuntu64Guest", "built_from": "os_install", "bill_dept": "EIS", "description": "Java web application.", "folder": "group-v4122", "networks": ["dvportgroup-95", "dvportgroup-92"], "disks": [40, 100]}'

If the request was successfully submitted and all parameters were accepted, the following Response Status, Headers and body will be received:

Code Block

language	text
title	Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, POST, OPTIONS, GET
Content-Length: 364
Content-Type: application/json
Date: Tue, 26 Apr 2016 18:24:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/fa276e28-a876-477a-ab40-0d2d84df9234
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7190
X-RateLimit-Reset: 1461697200

Code Block

language	py
title	Response Body
collapse	true

{
   "data": {
    "_links": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/new/8",
        "task": "https://vss-api.eis.utoronto.ca/v2/request/task/fa276e28-a876-477a-ab40-0d2d84df9234"
    },
    "message": "Request has been accepted for processing",
    "name": "Accepted",
    "request": {
        "id": 8,
        "status": "Submitted",
        "task_id": "fa276e28-a876-477a-ab40-0d2d84df9234"
    },
    "status": 202
    }
}

Note

Note that you will receive as well additional Hypermedia links contained in the _links attribute. Request object is the new virtual machine creation request which stores all parameters previously submitted and Task, is the unique task in charged of processing your request. Request and Task are both related, in terms of status, errors and warnings. Request will store any status or errors caught by the task, also it will pass the recently created VM Uuid.

Task

Request processing is almost instantaneous, however you could check the task progress by making a HTTP GET request to any given /v2/request/task/<task_id> endpoint.

Code Block

language	py
title	Response Body
collapse	true

 {
    "_links": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request", 
        "self": "https://vss-api.eis.utoronto.ca/v2/request/task/a57a3d4a-9e94-4822-a1d3-f99db1005dbd"
    }, 
    "data": {
        "result": {
            "current": 100, 
            "result": {
                "errors": [], 
                "warnings": [
                    "Fault Domain: FD3 ", 
                    "Created in: VSS > Sandbox > jm", 
                    "Network adapter 1: 00:50:56:92:50:6d: VL-1102-UTCS", 
                    "Network adapter 2: 00:50:56:92:3f:91: VL-1072-VSGAN"
                ]
            }, 
            "status": "1604P-desperate_thompson Processed", 
            "total": 100
        }, 
        "status": "SUCCESS"
    }, 
    "meta": {
        "count": 2, 
        "time": "0.00028s", 
        "user": "jm"
    }
}

Request

Checking the overall status of the request and also the resulting Uuid can be done by making a HTTP GET request to /v2/request/new/8 endpoint:

Code Block

language	py
title	Response Body
collapse	true

{
    "_link": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/new",
        "self": "https://vss-api.eis.utoronto.ca/v2/request/new/180"
    },
    "data": {
        "_links": {
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/6f642f4b-6be1-4fba-aabd-eab7f6366912",
            "user_data": "https://vss-api.eis.utoronto.ca/v2/request/new/180/user_data",
            "vm": "https://vss-api.eis.utoronto.ca/v2/vm/501219a5-a563-787c-f334-e7b65e829dca"
        },
        "annotation": [
            "VM Name: 1608T-sw-node2",
            "UTvssAdmin: Jose Manuel Lopez Lujan:416-577-7061:jm.lopez@utoronto.ca",
            "UTvssClient: EIS",
            "UTvssPurpose: Testing",
            "UTvssRequested: 2016-08-26 15:03:50 ",
            "UTvssInform: jm.lopez@utoronto.ca",
            "Description: deploying the new docker swarm cluster",
            ""
        ],
        "built_from": "image",
        "cpu": "1",
        "created_on": "2016-08-26 15:03:50 EDT",
        "disks": [
            10,
            40,
            40,
            40
        ],
        "domain": "domain-c5877",
        "dvd_cd": "",
        "folder": "group-v7505",
        "guest_os": "ubuntu64Guest",
        "high_io": false,
        "id": 180,
        "memory": "1",
        "message": {
            "errors": [],
            "warnings": null
        },
        "networks": [
            "dvportgroup-77"
        ],
        "source_image": "images/wily-server-cloudimg-amd64.ova",
        "status": "Processed",
        "task_id": "6f642f4b-6be1-4fba-aabd-eab7f6366912",
        "updated_on": "2016-08-26 15:04:42 EDT",
        "user": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/user"
            },
            "username": "josem"
        },
        "vm_name": "1608T-sw-node2",
        "vm_uuid": "501219a5-a563-787c-f334-e7b65e829dca",
        "workdir": "/data/imports/5279a6a4-87bc-4d5d-89a6-8458912d1b53"
    },
    "meta": {
        "count": 23,
        "time": "0.00968s",
        "user": "josem"
    }
}

Multiple Virtual Machines

To create multiple Virtual Machines, send a POST request to /v2/vm. Creating multiple VMs is quite similar to creating a single VM, but instead of sending name as a string, send names as an array and select the right built process, either clone or template. The following request body is used to deploy three VM from a VM template:

Code Block

language	py
title	Request Body

{"bill_dept": "EIS",
 "built_from": "template",
 "description": "Ubuntu cluster",
 "os": "ubuntu64Guest",
 "folder": "group-v4122",
 "source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8",
 "names": ["Ubuntu1", 
           "Ubuntu2", 
           "Ubuntu3"],
 "networks": ["dvportgroup-95",
              "dvportgroup-92"],
 "disks": [40, 100]}

Warning
The main difference between selecting clone or template as built process is that a source VM Template can deploy multiple instances concurrently, whereas a VM Clone can only be deployed concurrently when the source Virtual Machine is powered off. If VM is powered On, it can only be cloned one at a time.

HTTPie

Code Block

http POST "https://vss-api.eis.utoronto.ca/v2/vm" "Authorization: Bearer $TK" os='ubuntu64Guest' built_from='template' bill_dept='EIS' description='Ubuntu cluster' folder='group-v4122' networks:='["dvportgroup-95", "dvportgroup-92"]' disks:='[40, 100]' names:='["Ubuntu1", "Ubuntu2", "Ubuntu3"]' source_template=50123c4c-c810-5c0f-6203-eac67f0cb7e8

CURL

Code Block

curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm" -d '{"bill_dept": "EIS", "built_from": "template", "description": "Ubuntu cluster", "os": "ubuntu64Guest", "folder": "group-v4122", "source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8", "names": ["Ubuntu1", "Ubuntu2", "Ubuntu3"], "networks": ["dvportgroup-95", "dvportgroup-92"], "disks": [40, 100]}'

If the request was successfully submitted and all parameters were accepted, the following Response Status, Headers and body will be received:

Code Block

language	text
title	Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, POST, OPTIONS, GET
Content-Length: 682
Content-Type: application/json
Date: Wed, 27 Apr 2016 14:16:42 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7191
X-RateLimit-Reset: 1461769200

Code Block

language	py
title	Response Body
collapse	true

{
    "data": {
        "_links": {
            "requests": [
                "https://vss-api.eis.utoronto.ca/v2/request/new/26", 
                "https://vss-api.eis.utoronto.ca/v2/request/new/27", 
                "https://vss-api.eis.utoronto.ca/v2/request/new/28"
            ], 
            "tasks": [
                "https://vss-api.eis.utoronto.ca/v2/request/task/aa1cc5fa-94fc-473f-b29c-47f022745eb2", 
                "https://vss-api.eis.utoronto.ca/v2/request/task/97d1f968-dec5-4249-b23c-226b46258483", 
                "https://vss-api.eis.utoronto.ca/v2/request/task/0ec62b83-6c7f-47ae-8670-588449c3a2cb"
            ]
        }, 
        "message": "New VM Requests have been accepted for processing", 
        "name": "Accepted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.10215s", 
        "user": "jm"
    }
}

Note
The main difference between single and multiple vm creation/deployment is the number of requests and tasks returned by the API. In this case, since we required three VMs, we get the same number of requests and tasks as a result of the POST request, which can be queried individually to verify its progress or result.

Task

Request processing is almost instantaneous, however you could check the task progress by making a HTTP GET request to any given /v2/request/task/<task_id> endpoint.

Code Block

language	py
title	Response Body
collapse	true

 {
    "_links": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/", 
        "self": "https://vss-api.eis.utoronto.ca/v2/request/task/aa1cc5fa-94fc-473f-b29c-47f022745eb2"
    }, 
    "data": {
        "result": {
            "current": 100, 
            "result": {
                "errors": [], 
                "warnings": [
                    "Hard disk 1 capacity is the same. No change need to be done.", 
                    "Fault Domain: FD3 ", 
                    "Created in: VSS > Sandbox > jm", 
                    "Network adapter 1: 00:50:56:92:08:08: VL-1102-UTCS", 
                    "Network adapter 2: 00:50:56:92:14:fe: VL-1072-VSGAN"
                ]
            }, 
            "status": "1604T-Ubuntu1 Processed", 
            "total": 100
        }, 
        "status": "SUCCESS"
    }, 
    "meta": {
        "count": 2, 
        "time": "0.00597s", 
        "user": "jm"
    }
}

Requests

Checking the overall status of the requests and also the resulting Uuid can be done by making a HTTP GET request to /v2/request/new/26 - 28 endpoint:

Code Block

language	py
title	Response Body
collapse	true

{
    "_link": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/new", 
        "self": "https://vss-api.eis.utoronto.ca/v2/request/new/26"
    }, 
    "data": {
        "_links": {
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/aa1cc5fa-94fc-473f-b29c-47f022745eb2", 
            "vm": "https://vss-api.eis.utoronto.ca/v2/vm/5012826a-6a1a-815a-249d-7d6eb640f020"
        }, 
        "annotation": [
            "VM Name: 1604T-Ubuntu1", 
            "UTvssAdmin: JM Lopez Lujan:416-123-1234:jm.lopez@utoronto.ca", 
            "UTvssClient: EIS", 
            "UTvssPurpose: Test", 
            "UTvssRequested: 2016-04-27 10:16:42 ", 
            "UTvssInform: jm.lopez@utoronto.ca", 
            "Description: Ubuntu cluster", 
            ""
        ], 
        "built_from": "template", 
        "cpu": "1", 
        "created_on": "2016-04-27 10:16:42 EDT", 
        "disks": [
            40, 
            100
        ], 
        "domain": "domain-c5877", 
        "dvd_cd": "", 
        "folder": "group-v4122", 
        "guest_os": "ubuntu64Guest", 
        "high_io": false, 
        "id": 26, 
        "memory": "1", 
        "message": {
            "errors": [], 
            "warnings": [
                "Hard disk 1 capacity is the same. No change need to be done.", 
                "Fault Domain: FD3 ", 
                "Created in: VSS > Sandbox > jm", 
                "Network adapter 1: 00:50:56:92:08:08: VL-1102-UTCS", 
                "Network adapter 2: 00:50:56:92:14:fe: VL-1072-VSGAN"
            ]
        }, 
        "networks": [
            "dvportgroup-95", 
            "dvportgroup-92"
        ], 
        "source_template": "50123c4c-c810-5c0f-6203-eac67f0cb7e8", 
        "source_vm": null, 
        "status": "Processed", 
        "task_id": "aa1cc5fa-94fc-473f-b29c-47f022745eb2", 
        "updated_on": "2016-04-27 10:26:00 EDT", 
        "user": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/user"
            }, 
            "id": 1, 
            "username": "jm"
        }, 
        "vm_name": "1604T-Ubuntu1", 
        "vm_uuid": "5012826a-6a1a-815a-249d-7d6eb640f020"
    }, 
    "meta": {
        "count": 23, 
        "time": "0.00541s", 
        "user": "jm"
    }
}

List

Virtual machines

In order to list all your Virtual Machines you should make a HTTP GET request to the endpoint /v2/vm:

The following examples use HTTPie and CURL to request ALL Virtual Machine managed by given user without filters:

Code Block

language	bash

http GET "https://vss-api.eis.utoronto.ca/v2/vm" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm"

HTTP response data would look something like:

Code Block

language	py
title	Response
collapse	true

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm?short=1&per_page=5"
    },
    "data": [
        {
            "_linkshostName": {
   "HOTH",
            "selfipAddress": "https://vss-api.eis.utoronto.ca/v2/vm/5012bbfb-137e-c4f5-7a85-c837351f786b"",
             }"moref": "vm-4210",
            "name": "1608T-ubuntu-15.10_x641409P-hoth",
            "uuidpowerState": "5012bbfb-137e-c4f5-7a85-c837351f786b"
poweredOff",
       },     "uuid": "50127974-aa4a-c215-f9f0-e1ab8a4ef050"
   {     },
       "_links": {
   
            "selfhostName": "https://vss-apiglog-app01.eis.utoronto.ca/v2/vm/5012aa6d-6e6b-e5c7-87a5-713853308880"",
             }"ipAddress": "192.168.2.222",
            "namemoref": "1608T-ubuntu-15.04_x64vm-12178",
            "uuidname": "5012aa6d1803D-6e6bgraylog-e5c7app-87a5-713853308880"0",
          }  "powerState": "poweredOn",
     {       "uuid": "5012f72a-f9c7-366f-5cf0-e1ac6afe4466"
    "_links": {   },
        {
    "self": "https://vss-api        "hostName": "glog-app02.eis.utoronto.ca/v2/vm/501264bc-5d2d-3330-e0d9-562309e33331"",
             }"ipAddress": "192.168.2.122",
            "namemoref": "CentOS-7-x86_64-VMwarevm-12075",
            "uuidname": "501264bc1803D-5d2d-3330-e0d9-562309e33331"graylog-es1",
             },"powerState": "poweredOn",
             {"uuid": "50129e9f-38c5-ba9a-14d1-a1023fbc3aeb"
        },
   "_links": {    {
            "selfhostName": "https://vss-api.eis.utoronto.ca/v2/vm/50123967-ab62-e8af-1c1a-9e43683ac208"gpu-dh-108",
            "ipAddress": "192.168.1.155",
            "moref": "vm-15854",
             }"name": "1811D-ubuntu",
            "namepowerState": "1608T-tender_mccarthypoweredOn",
            "uuid": "50123967501257e0-ab6281f5-e8af9c2a-1c1a84e5-9e43683ac208e900212fef76"
        } ,
      ],  {
  "meta": {         "counthostName": 4,"ubuntu",
            "timeipAddress": "0.00713s",
            "usermoref": "jm"vm-13053",
         } }

If you wish to display a quick summary in your main VM list, just include summary=1 in the query string as follows:

Code Block

language	bash

http GET "name"https://vss-api.eis.utoronto.ca/v2/vm?summary=1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm?summary=1"

Code Block

language	py
title	Response
collapse	true

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
   : "1807P-Ubuntu-18.04-server-tmpl",
            "powerState": "poweredOff",
            "uuid": "50120242-3ea3-d7ba-b6a5-14ffa8565b65"
        }
    ],
    "selfmeta": "https://vss-api.eis.utoronto.ca/v2/vm"
{
   },     "datacount": [
        {
   5,
        "_linkspages": {
   
            "selffirst_url": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510"?per_page=5&page=1&expand=True",
             }"last_url": "https://vss-api.eis.utoronto.ca/v2/vm?per_page=5&page=5&expand=True",
            "cpuCountnext_url": "https://vss-api.eis.utoronto.ca/v2/vm?per_page=5&page=2&expand=True",
            "folderpage": 1,
 {           "pages": 5,
    "_links": {       "per_page": 5,
            "selfprev_url": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736"
                },
   null,
            "moreftotal": "group-v6736", 25
        },
        "nametime": "APIDemo0.03134s",
       
        "parentuser": "jm"
            },
            "guestFullName": "Other 3.x or later Linux (64-bit)",
            "ipAddress": null,
            "memoryGB": 2.0,
            "name": "1608T-stoic_carson",
            "overallStatus": "green",
            "powerState": "poweredOff",
            "provisionedGB": 12.25,
            "uuid": "5012689b-071a-145b-584a-9a9b49873510"
        }
	...
    ],
    "meta": {
        "count": 1,
        "time": "0.78135s",
        "user": "jm"
    }
}

Included attributes are described in the following table:

NameTypeDescriptionuuidstring128-bit UUID of

}
}

Included attributes are described in the following table:

Name	Type	Description
uuid	string	128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID.
moref	string	Managed object reference of the vm
name	string	Virtual Machine name including VSS prefix.
guestFullName	string	This is the The full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional.
guestId	string	The guest operating system identifier.
ipAddress	string	Primary IP address assigned to the guest operating system, if knownthe guest operating system, if known.
hostName	string	Guest hostname. Provided only when VMware Tools is running.
ipAddress	string	Guest main IP Address. Provided only when VMware Tools is running.
memoryGB	integer	Memory size of the virtual machine, in Gigabytes.
cpuCount	integer	Number of processors in the virtual machine.
overallStatus	string	VM general "health" value: gray: The status is unknown. green: The entity is OK. red: The entity definitely has a problem. yellow: The entity might have a problem.
powerState	string	The current power state of the virtual machine. The state could be: poweredOff or poweredOn
provisionedGB	integer	Sum of Committed and Uncommitted storage.
folder	object	Folder object which contains current VM

Sorting

Virtual Machines can be sorted mainly by name and uuid as follows:

Code Blocklanguagebash

is unknown. green: The entity is OK. red: The entity definitely has a problem. yellow: The entity might have a problem.
powerState	string	The current power state of the virtual machine. The state could be: poweredOff or poweredOn
provisionedGB	integer	Sum of Committed and Uncommitted storage.
folder	object	Folder object which contains current VM
folder_moref	string	Folder managed object reference
toolsRunningStatus	string	VMware Tools running status.
toolsVersion	string	VMware Tools version.
toolsVersionStatus	string	VMware Tools version status.
version	string	Virtual hardware version.

Paging

All requests to the /vm URL are paginated. The response body includes a 'meta.pages' key with everything to navigate through the results, for instance:

Key	Description
first_url	Contain the URLs to navigate through results.
last_url
prev_url
next_url
page	Current page
pages	Total number of pages
per_page	Results per page. Maximum 250; Default 10.
total	Total number of results

Results per page can be set by including the parameter in the URL query, so we can get the desired number of elements per page, for example:

Code Block

http GET "https://vss-api.eis.utoronto.ca/v2/vm?sort=name"per_page=200" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" http-X GET "https://vss-api.eis.utoronto.ca/v2/vm?sortper_page=uuid" "Authorization: Bearer $TK"

However, if summary=1 is included in the query string, there are more attributes the virtual machines can be sorted by:

name
uuid
folder
overallStatus
powerState
memoryGB
cpuCount
guestFullName

And then, they can be included in the sort attribute as shown below

1500"

Sorting

The resource provides also attribute sorting by adding the sort parameter in the URL query string in the following format:

Code Block
sort=<field_name>,<asc\|desc>

For example:

Code Block

language	bash

http GET "https://vss-api.eis.utoronto.ca/v2/vm?summary=1&sort=cpuCountname,desc" "Authorization: Bearer $TK"
http GET "https://vss-api.eis.utoronto.ca/v2/vm?summary=1&sort=guestFullName" "Authorization: Bearer $TK"

Filters

The main Virtual Machine resource has four main filters to narrow down the number of VMs shown in the result or to locate a VM by hostname or ip address.

NameDescriptionnameVirtual Machine name string to filter VMsipPrimary IP address assigned to the Guest operating system.dnsHostname of the guest operating system.pathInventory path in the following format EIS-DCB/vm/Public/jm/APIDemo/1605T-VMTest_1summaryEnables VM summary in results.

/v2/vm?sort=uuid,asc" "Authorization: Bearer $TK"

Filtering

Virtual Machines can be filtered by adding the filter argument to the query string in the following format:

Code Block
filter=<field_name>,<operator>,<value>

Operators can be:

Operator	Description
eq	Equals
ne	Not equal
lt	Lower than
le	Lower equal
gt	Greater than
ge	Greater equal
like	Matching pattern
in	Match value in many items separated by commas

Filter Virtual Machine resource by any of the following

Attribute	Filter
name	name
ipAddress	ip_address
hostname	hostname
powerState	power_state
cpuCount	cpu_count
overallStatus	overall_status
toolsVersion	tools_version
toolsVersionStatus	tools_version_status
version	version

The following examples show how to implement a GET request with the first three parameters shown below. The result is similar to the previous section.

Code Block

language	bash

http GET "https://vss-api.eis.utoronto.ca/v2/vm?name=Testfilter=name,like,%Test%" "Authorization: Bearer $TK"
http GET "https://vss-api.eis.utoronto.ca/v2/vm?filter=ip=,eq,10.2.1.2" "Authorization: Bearer $TK"
http GET "https://vss-api.eis.utoronto.ca/v2/vm?filter=dns=wiki.eis.utoronto.ca" "Authorization: Bearer $TK"
http GET "https://vss-api,like,wiki.eis.utoronto.ca/v2/vm?path=EIS-DCB/vm/Public/jm/APIDemo/1605T-VMTest_1" "Authorization: Bearer $TK"

Filtering by name can be done as follows:

Code Block

language	bash

http GET "https://vss-api.eis.utoronto.ca/v2/vm?name=Testfilter=name,like,%Test%" "Authorization: Bearer $TK"

HTTP response data would look something like:

Code Block

language	bash
title	HTTP Response
collapse	true

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/", 
        "self": "https://vss-api.eis.utoronto.ca/v2/vm"
    }, 
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db"
            }, 
            "name": "1604Q-VMTest_1", 
            "uuid": "5012bd15-c20c-a971-aa68-af1a3cf3d0db"
        }
    ], 
    "meta": {
        "count": 1, 
        "time": "1.86220s", 
        "user": "jm"
    }
}

Note
From now on, you will need the UUID of any virtual machine, provided by the either the uuid attribute or in the "_links" section, to get further information and eventually to modify its configuration.

Specific virtual machine info

Some of the attributes will have an object value. Such is the case of guest, hardware, network, config and vss.

Name	Type	Description
uuid	string	VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID.
name	string	Virtual Machine name including VSS prefix.
Config	VM Configuration
bootdelay	integer	Delay in milliseconds before starting the boot sequence. The boot delay specifies a time interval between virtual machine power on or restart and the beginning of the boot sequence.
os	string	Operating system configured in the virtual machine
Folder	Logical Folder
name	string	Immediate folder holding VM
parent	string	Parent folder holding the VM
path	string	Full path to immediate folder
moref	string	Managed object reference to parent folder
Guest	Guest status and configuration
guestFullName	string	This is the full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional.
guestId	string	Guest operating system configured on a virtual machine.
hostName	string	Hostname of the guest operating system, if known.
ipAddress	string	List of IP address assigned to the guest operating system, if known.
toolsStatus	string	Current running status of VMware Tools in the guest operating system, if known.
Note	Virtual Machine Metadata
note	string	Virtual Machine full annotation
client	string	Client notes
Name
full_name	string	VM full name including VSS prefix.
Hardware	Virtual Machine Hardware configuration
cpuCount	integer	Number of processors in the virtual machine.
coresPerSocket	integer	Number of cores used to distribute virtual CPUs among sockets in this virtual machine. If the value is unset it implies to numCoresPerSocket = 1.
memoryMB	integer	Memory size of the virtual machine, in megabytes.
devices	string	List of strings holding controllers, cd/dvd, disks and nics configured in the VM
version	string	The version string for this virtual machine.
Storage	Storage summary
provisionedGB	integer	Sum of Committed and Uncommitted storage.
uncommittedGB	integer	Additional storage space, in bytes, potentially used by this virtual machine on all datastores.
committedGB	integer	Total storage space, in bytes, committed to this virtual machine across all datastores.
unsharedGB	integer	Total storage space, in bytes, occupied by the virtual machine across all datastores, that is not shared with any other virtual machine.
State	Runtime status related attributes
overallStatus	string	VM general "health" value: gray: The status is unknown. green: The entity is OK. red: The entity definitely has a problem. yellow: The entity might have a problem.
powerState	string	The current power state of the virtual machine.
alarms	boolean	Whether the VM has triggered alarms.
Snapshot	Virtual Machine Snapshot information
exist	boolean	Whether the current virtual machine has Snapshots
VSS	VSS Metadata
Admin	string	Admin responsible of this VM.
Client	string	Custom client key-value notes.

The following example, requests information about a particular VM using its base resource /v2/vm and appending the UUID to get the URI /vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db/.

Code Block

language	bash

http GET "https://vss-api.eis.utoronto.ca/v2/vm/5012bd15-c20c-a971-aa68-af1a3cf3d0db" "Authorization: Bearer $TK"

HTTP response data would look something like:

Code Block

language	py
title	Response
collapse	true

{
  "data": {
    "vss": {
      "admin": "JM Lopez Lujan:416-577-7061:jm@eis.utoronto.ca", 
      "client": "EIS", 
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/vss"
      }
    }, 
    "hardware": {
      "version": "vmx-10", 
      "cpu": {
        "cpuCount": 2, 
        "_links": {
          "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/cpu"
        }
      }, 
      "devices": {
        "nics": [
          {
            "macAddress": "00:50:56:92:28:7a", 
            "_links": {
              "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/nic/1"
            }, 
            "network": {
              "moref": "dvportgroup-95", 
              "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/network/dvportgroup-95"
              }
            }, 
            "unit": "1"
          }
        ], 
        "disks": [
          {
            "capacityGB": 10.0, 
            "_links": {
              "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/disk/1"
            }, 
            "unit": "1"
          }
        ], 
        "floppies": [
          {
            "backing": "client", 
            "_links": {
              "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/floppy/1"
            }, 
            "label": "Floppy drive 1"
          }
        ], 
        "cds": [
          {
            "backing": "client", 
            "_links": {
              "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/cd/1"
            }, 
            "unit": "1"
          }
        ]
      }, 
      "memory": {
        "_links": {
          "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/memory"
        }, 
        "memoryGB": 2.0
      }
    }, 
    "guest": {
      "toolsStatus": "guestToolsUnmanaged", 
      "hostName": null, 
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/guest"
      }, 
      "guestId": null, 
      "ipAddress": [], 
      "guestFullName": null
    }, 
    "uuid": "5012689b-071a-145b-584a-9a9b49873510", 
    "storage": {
      "uncommittedGB": 11.64, 
      "provisionedGB": 12.25, 
      "committedGB": 0.6, 
      "unsharedGB": 0.6
    }, 
    "name": {
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/name"
      }, 
      "full_name": "1608T-stoic_carson"
    }, 
    "note": {
      "note": {
        "_links": {
          "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/note"
        }
      }, 
      "client": {
        "_links": {
          "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/note/client"
        }, 
        "tags": []
      }
    }, 
    "state": {
      "alarms": false, 
      "powerState": "poweredOff", 
      "overallStatus": "green", 
      "_links": {
        "alarm": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/alarm", 
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/state", 
        "event": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/event", 
        "domain": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/domain"
      }
    }, 
    "snapshot": {
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/snapshot"
      }, 
      "exist": false
    }, 
    "folder": {
      "path": "VSS > Sandbox > jm > APIDemo", 
      "moref": "group-v6736", 
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736"
      }, 
      "name": "APIDemo", 
      "parent": "jm"
    }, 
    "config": {
      "os": {
        "guestId": "other3xLinux64Guest", 
        "_links": {
          "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/os"
        }
      }, 
      "boot": {
        "delayMs": 0, 
        "_links": {
          "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/boot"
        }
      }
    }
  }, 
  "meta": {
    "count": 11, 
    "user": "jm", 
    "time": "0.54539s"
  }, 
  "_links": {
    "export": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/export", 
    "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510", 
    "console": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/console", 
    "template": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/template", 
    "performance": "https://vss-api.eis.utoronto.ca/v2/vm/5012689b-071a-145b-584a-9a9b49873510/performance"
  }
}

Delete

Single Virtual Machine

To delete an existent Virtual Machine, send a DELETE request to /v2/vm/<vm_uuid> and a change request to decommission requested VM will be submitted.

HTTPie

Code Block
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607" "Authorization: Bearer $TK"

CURL

Code Block
curl -H "Authorization: Bearer $TK" $TK -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607"

If the request was successfully submitted, the following Response Status, Headers and body will be received:

Code Block

language	text
title	Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, DELETE, OPTIONS, GET
Content-Length: 398
Content-Type: application/json
Date: Thu, 28 Apr 2016 15:32:55 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7195
X-RateLimit-Reset: 1461859200

Code Block

language	py
title	Response Body
collapse	true

{
   "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/12", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6"
        }, 
    	"message": "Request has been accepted for processing",
    	"name": "Accepted",
    	"request": {
    	    "id": 12,
    	    "status": "Submitted",
    	    "task_id": "7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6"
    	},
    	"status": 202
    }
}

Task

Request processing is almost instantaneous, however you could check the task progress by making a HTTP GET request to any given /v2/request/task/<task_id> endpoint.

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/", 
        "self": "https://vss-api.eis.utoronto.ca/v2/request/task/7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6"
    }, 
    "data": {
        "result": {
            "current": 100, 
            "result": {
                "errors": [], 
                "warnings": [
                    "Virtual Machine 1604T-Ubuntu3 has been deleted."
                ]
            }, 
            "status": "1604T-Ubuntu3 Processed", 
            "total": 100
        }, 
        "status": "SUCCESS"
    }, 
    "meta": {
        "count": 2, 
        "time": "0.00865s", 
        "user": "jm"
    }
}

Requests

Checking the overall status of the requests and also its result can be done by making a HTTP GET request to /v2/request/change/26 - 28 endpoint:

Code Block

language	py
title	Response Body
collapse	true

{
    "_link": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/change", 
        "self": "https://vss-api.eis.utoronto.ca/v2/request/change/12"
    }, 
    "data": {
        "_links": {
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6", 
            "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607"
        }, 
        "attribute": "state", 
        "created_on": "2016-04-28 11:32:55 EDT", 
        "id": 12, 
        "message": {
            "errors": [], 
            "warnings": [
                "Virtual Machine 1604T-Ubuntu3 has been deleted."
            ]
        }, 
        "status": "Processed", 
        "task_id": "7e8e4a7c-7c09-42d2-86e1-41ff5ea530c6", 
        "updated_on": "2016-04-28 11:32:56 EDT", 
        "user": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/user"
            }, 
            "id": 1, 
            "username": "jm"
        }, 
        "user_id": 1, 
        "value": {
            "state": "delete"
        }, 
        "vm_name": "1604T-Ubuntu3", 
        "vm_uuid": "50125d11-a8d6-2af7-c01e-dc6f6be0e607"
    }, 
    "meta": {
        "count": 13, 
        "time": "0.00572s", 
        "user": "jm"
    }
}

Versions Compared

Old Version 57

New Version 58

Key

Introduction

Create

Single Virtual Machine

HTTPie

CURL

Task

Request

Multiple Virtual Machines

HTTPie

CURL

Task

Requests

List

Virtual machines

Sorting

Paging

Sorting

Filters

Filtering

Specific virtual machine info

Delete

Single Virtual Machine

HTTPie

CURL

Task

Requests

Page Comparison

Versions Compared

Old Version 57

New Version 58

Key

Introduction

Create

Single Virtual Machine

HTTPie

CURL

Task

Request

Multiple Virtual Machines

HTTPie

CURL

Task

Requests

List

Virtual machines

Sorting

Paging

Sorting

Filters

Filtering

Specific virtual machine info

Delete

Single Virtual Machine

HTTPie

CURL

Task

Requests