Introduction

VMware supports most of Windows, Linux, Unix, Macintosh, and other operating systems (full list here), however we have carefully selected the latest, most used in our user community and those we know are stable enough in our environment.

The following table shows a brief description and HTTP methods allowed to interact with the Supported Operating System resource.

Resource	URI	Description	GET	POST	PUT	PATCH
Supported Operating Systems	/os	List supported operating systems and their attributes

On this page:

TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource:

curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username>

For example, extracting the token with the jq command:

TK=$(curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> | jq -r '.token')

List

There are more than 60 operating systems to use in our environment and to list them all, a GET request should be made to /v2/os as show below:

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

As a result, there will be a list of JSON objects with two attributes each: id and name described in the following table:

Name	Type	Description
guest_id	string	Guest OS identifier. Used as value of attribute os in /v2/vm resource to crate VMs or in /v2/vm/<vm_uuid/guest/os to update given VM Guest OS Support.
full_name	string	Guest OS full name.
family	string	Guest Os family

The following example is a response body with only a few elements. In practice you will get more than 60 elements.

Paging

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

Meta key

    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/os"
        },
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=10&page=8",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=10&page=2",
            "page": 1,
            "pages": 8,
            "per_page": 10,
            "prev_url": null,
            "total": 71
        },
        "time": "0.00444s",
        "user": "josem"
    }

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 100; 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:

http GET "https://vss-api.eis.utoronto.ca/v2/os?per_page=5" "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/os?per_page=5"

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/os/1",
        "https://vss-api.eis.utoronto.ca/v2/os/2",
        "https://vss-api.eis.utoronto.ca/v2/os/3",
        "https://vss-api.eis.utoronto.ca/v2/os/4",
        "https://vss-api.eis.utoronto.ca/v2/os/5"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/os?per_page=5"
        },
        "count": 5,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=5&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=5&page=15",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=5&page=2",
            "page": 1,
            "pages": 15,
            "per_page": 5,
            "prev_url": null,
            "total": 71
        },
        "time": "0.00399s",
        "user": "josem"
    }
}

In this example, you can see the number of pages have increased from 8 to 15 and the '_link.self' key has included the parameter 'per_page' in the URL query.

Expansion

OS resource expansion is disabled by default, therefore elements found are listed as URLs. However, if you wish to display its contents add the expand=1 to URL query string and you will get the actual element in full JSON format, as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=22&expand=1" "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=22&expand=1"

Response Body

{
    "data": [
        {
            "full_name": "Solaris 10 (32 bit) (experimental)",
            "guest_id": "solaris10Guest",
			"family": "solarisGuest"
            "id": 22
        }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=22&expand=1"
        },
        "count": 1,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=71&expand=1",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=23&expand=1",
            "page": 22,
            "pages": 71,
            "per_page": 1,
            "prev_url": "https://vss-api.eis.utoronto.ca/v2/os?per_page=1&page=21&expand=1",
            "total": 71
        },
        "time": "0.00426s",
        "user": "josem"
    }
}

Filtering

Supported operating systems can be filtered by adding the filter argument to the query string in the following format:

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

A resource can be filtered by as many attributes the object has, for instance /os can be filtered by guest_id, full_name and family. Thus, the following example will filter CentOS operating systems:

http GET "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,CentOS%&expand=1" "Authorization: Bearer $TK" 

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,CentOS%&expand=1"

Response Body

{
    "data": [
  {
    "family": "linuxGuest",
    "full_name": "CentOS 4/5 (64-bit)",
    "guest_id": "centos64Guest",
    "id": 24
  },
  {
    "family": "linuxGuest",
    "full_name": "CentOS 6 (64-bit)",
    "guest_id": "centos6_64Guest",
    "id": 70
  },
  {
    "family": "linuxGuest",
    "full_name": "CentOS 6",
    "guest_id": "centos6Guest",
    "id": 26
  },
  {
    "family": "linuxGuest",
    "full_name": "CentOS 7 (64-bit)",
    "guest_id": "centos7_64Guest",
    "id": 15
  },
  {
    "family": null,
    "full_name": "CentOS 7",
    "guest_id": "centos7Guest",
    "id": 78
  },
  {
    "family": "linuxGuest",
    "full_name": "CentOS 8 (64-bit)",
    "guest_id": "centos8_64Guest",
    "id": 95
  },
  {
    "family": "linuxGuest",
    "full_name": "CentOS 4/5",
    "guest_id": "centosGuest",
    "id": 2
  }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,CentOS%&expand=1"
        },
        "count": 2,
        "filter": "full_name,like,CentOS%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name%2Clike%2CCentOS%25&per_page=10&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name%2Clike%2CCentOS%25&per_page=10&page=1&expand=1",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 2
        },
        "time": "0.00178s",
        "user": "josem"
    }
}

Sorting

Operating systems can be sorted by adding the sort parameter in the URL query string in the following format:

sort=<field_name>,<asc|desc>

The following example shows how to sort by guest_id , filter by full_name and expand results :

http GET "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,Windows%&expand=1&sort=guest_id,asc" "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,Windows%&expand=1&sort=guest_id,asc"

Response Body

{
    "data": [
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 7 (64 bit)",
    "guest_id": "windows7_64Guest",
    "id": 34
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 7",
    "guest_id": "windows7Guest",
    "id": 17
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2008 R2 (64 bit)",
    "guest_id": "windows7Server64Guest",
    "id": 8
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 8 (64 bit)",
    "guest_id": "windows8_64Guest",
    "id": 44
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 8 and Windows Server 2012",
    "guest_id": "windows8Guest",
    "id": 60
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 8 Server (64 bit) and Windows Server 2012 (64 bit)",
    "guest_id": "windows8Server64Guest",
    "id": 32
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 10 (64 bit) and Microsoft Windows Server 2016 (64-bit)",
    "guest_id": "windows9_64Guest",
    "id": 42
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows 10",
    "guest_id": "windows9Guest",
    "id": 63
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2016 (64-bit)",
    "guest_id": "windows9Server64Guest",
    "id": 54
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2008 (64-bit)",
    "guest_id": "winLonghorn64Guest",
    "id": 14
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2008 (32-bit)",
    "guest_id": "winLonghornGuest",
    "id": 84
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Small Business Server 2003",
    "guest_id": "winNetBusinessGuest",
    "id": 80
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003, Datacenter Edition (64 bit)",
    "guest_id": "winNetDatacenter64Guest",
    "id": 23
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003 Datacenter Edition",
    "guest_id": "winNetDatacenterGuest",
    "id": 66
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003, Enterprise Edition (64 bit)",
    "guest_id": "winNetEnterprise64Guest",
    "id": 77
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003, Enterprise Edition",
    "guest_id": "winNetEnterpriseGuest",
    "id": 86
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003 Standard Edition (64 bit)",
    "guest_id": "winNetStandard64Guest",
    "id": 1
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003, Standard Edition",
    "guest_id": "winNetStandardGuest",
    "id": 40
  },
  {
    "family": "windowsGuest",
    "full_name": "Microsoft Windows Server 2003, Web Edition",
    "guest_id": "winNetWebGuest",
    "id": 56
  }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,Windows%&expand=1&sort=guest_id,asc"
        },
        "count": 10,
        "filter": "full_name,like,Windows%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/os?sort=guest_id%2Casc&filter=full_name%2Clike%2CWindows%25&page=1&expand=1&per_page=10",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/os?sort=guest_id%2Casc&filter=full_name%2Clike%2CWindows%25&page=2&expand=1&per_page=10",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/os?sort=guest_id%2Casc&filter=full_name%2Clike%2CWindows%25&page=2&expand=1&per_page=10",
            "page": 1,
            "pages": 2,
            "per_page": 10,
            "prev_url": null,
            "total": 17
        },
        "sort": "guest_id,asc",
        "time": "0.00485s",
        "user": "josem"
    }
}

Operating Systems

Introduction

List

Paging

Expansion

Filtering

Sorting