Hypervisors REST API

Use this REST API to manage hypervisors.

Available HTTP Methods

Table 1. REST API for hypervisors
HTTP Method	URI Pattern	Data Format	Success Codes	Error Codes
GET	/resources/hypervisors	application/json	200 Returns the list of hypervisors defined in Cloud Pak System. See the example for a sample of the data returned.	403 This code is returned if the requester has not been assigned the cloud administration role. 500 This code is returned if the IBM® Cloud Pak Software encountered an internal error while processing the request.
POST	/resources/hypervisors	application/json	201 The hypervisor has been created and is included in the response body. The URL of the new hypervisor is included in the Location header of the response.	400 This code is returned if there are problems parsing the JSON data in the request. 403 This code is returned if the requester has not been assigned the cloud administration role. 500 This code is returned if the IBM Cloud Pak Software encountered an internal error while processing the request.
GET	/resources/hypervisors/{id}	application/json	200 Returns information about a hypervisor defined to the IBM Cloud Pak Software.	403 This code is returned if the requester has not been assigned the cloud administration role. 404 This code is returned if the requested hypervisor is not defined. 500 This code is returned if the IBM Cloud Pak Software encountered an internal error while processing the request.
PUT	/resources/hypervisors/{id}	application/json	200 The hypervisor was successfully updated. The response body contains a JSON representation of the hypervisor's current state.	400 This code is returned if there are problems parsing the JSON data in the request. 403 This code is returned if the requester has not been assigned the cloud administration role. 404 This code is returned if the request references a resource that is not defined. 500 This code is returned if the IBM Cloud Pak Software encountered an internal error while processing the request.
DELETE	/resources/hypervisors/{id}		204 The hypervisor has been deleted.	403 This code is returned if the requester has not been assigned the cloud administration role. 404 This code is returned if the requested hypervisor is not defined. 500 This code is returned if the IBM Cloud Pak Software encountered an internal error while processing the request.

A hypervisor has the following attributes:

address

Specifies the host name or IP address (dotted decimal notation) at which the hypervisor can be reached. This field expects a string value with a maximum of 1024 characters.

certified

Specifies if the SSL certificate from this hypervisor has been certified. Cloud Pak System does not deploy patterns to a hypervisor until it has been certified. Note that the SSL certificate from the hypervisor must be retrieved before the hypervisor can be certified. The following string values are valid:

T: Hypervisor has been certified.
F: Hypervisor is not certified.
I: Hypervisor is not certified and resources have not been discovered.

cloud

Specifies the uniform resource identifier (URI) of the cloud group to which this hypervisor has been assigned. The URI is relative and should be resolved against the URI of the hypervisor.

created

Specifies the creation time of the hypervisor, represented as the number of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and is automatically generated by the system.

currentmessage

Specifies the message associated with the current status of the hypervisor. For example, it could give more details about the problem that caused the hypervisor to be placed in an error state. This field contains an 8 character string value that is generated by the system.

currentmessage_text

Specifies the textual representation of currentmessage. This is a string representation of currentmessage in the preferred language of the requester and is automatically generated by the system. This field has a maximum of 1024 characters.

currentstatus

Specifies a string constant representing the current status of the hypervisor. This field is an 8 character string value that is automatically generated by the system.

currentstatus_text

Specifies a textual representation of currentstatus. This is a string representation of currentstatus in the preferred language of the requester and is automatically generated by the system.

desiredstatus

Specifies the preferred status of the hypervisor. Setting this value will cause Cloud Pak System to initiate the steps that are needed to get the hypervisor to this state. This value is an 8 character string and can only be set to one of the following values:

RM01025: Maintenance mode
RM01006: Started

desiredstatus_text

Specifies a textual representation of desiredstatus. This is a string representation of desiredstatus in the preferred language of the requester and is automatically generated by the system.

id

Specifies the ID of the hypervisor. This attribute can be a string or a number. When the attribute is a string, there are practical limits on the string length due to the way the string is generated: ("PM-" + numeric id).

name

Specifies the display name associated with this hypervisor. This field expects a string value with a maximum of 64 characters and must be unique among all hypervisors defined to Cloud Pak System.

networks

Specifies the list of URIs of the networks associated with this hypervisor. The URIs are relative should be resolved against the URI of the hypervisor that contains them. This list of networks is automatically generated as part of the discovery process and cannot be changed.

password

Specifies the password used to log on to the hypervisor. This field expects a string value with a maximum of 128 characters.

storage

Specifies the list of URIs of the storage associated with this hypervisor. The URIs are relative should be resolved against the URI of the hypervisor that contains them. This list of storage is automatically generated as part of the discovery process and cannot be changed.

type

Specifies the type of this hypervisor. This value must be set to:

ESX

This field expects a string value with a maximum of 128 characters.

updated

Specifies the time the hypervisor was last updated, represented as the number of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and is automatically generated by the system.

userid

Specifies the user ID used to log on to the hypervisor. This field expects a string value with a maximum of 128 characters.

UUID

The universally unique identifier for the hypervisor. For hypervisors that do not have a UUID, this value will be "none".

GET /resources/hypervisors example


[
{
"address": "https://172.16.15.250/sdk",
"certified": "T",
"cloud": "/resources/clouds/7",
"created": 1254889411919,
"currentmessage": "RM03103",
"currentmessage_text": "Started (move to maintenance mode to make changes)",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01006",
"desiredstatus_text": "Started",
"id": 16,
"name": "virtualwas",
"networks": [
"/resources/networks/38",
"/resources/networks/39"
],
"password": "125488941166924",
"storage": [
"/resources/storage/56",
"/resources/storage/57"
],
"type": "ESX",
"updated": 1254889464232,
"userid": "root"
},
{
"address": "172.16.0.5",
"certified": "T",
"cloud": "/resources/clouds/17",
"created": 1255049179858,
"currentmessage": "RM03103",
"currentmessage_text": "Started (move to maintenance mode to make changes)",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01006",
"desiredstatus_text": "Started",
"id": "PM-19",
"name": "IBM 8204 E8A 10BC4A1",
"networks": [
"/resources/networks/40",
"/resources/networks/41"
],
"password": "125504917100029",
"storage": [
"/resources/storage/58",
"/resources/storage/59",
"/resources/storage/60"
],
"type": "PowerVM",
"updated": 1255049245832,
"userid": "root"
}
]

See the description of GET /resources/hypervisors/{id} for attribute details.

POST /resources/hypervisors example

Request JSON:


{
   "address": "anotherhypervisor.mycompany.com",
   "name": "another hypervisor",
   "password": "thepassword",
   "type": "ESX",
   "userid": "root"
}

Response JSON:


{
   "address": "https://anotherhypervisor.mycompany.com/sdk",
   "certified": "I",
   "cloud": null,
   "created": 1245249680477,
   "currentmessage": "RM03106",
   "currentmessage_text": "Maintenance mode (must add to a cloud group to start)",
   "currentstatus": "RM01025",
   "currentstatus_text": "Maintenance mode",
   "desiredstatus": "RM01025",
   "desiredstatus_text": "Maintenance mode",
   "id": 5,
   "name": "another hypervisor",
   "networks": [
   ],
   "password": "124524968047629",
   "storage": [
   ],
   "type": "ESX",
   "updated": 1245249680477,
   "userid": "root"
}

GET /resources/hypervisors/{id} example


{
"address": "172.16.0.5",
"certified": "T",
"cloud": "/resources/clouds/17",
"created": 1255049179858,
"currentmessage": "RM03103",
"currentmessage_text": "Started (move to maintenance mode to make changes)",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01006",
"desiredstatus_text": "Started",
"id": "PM-19",
"name": "IBM 8204 E8A 10BC4A1",
"networks": [
"/resources/networks/40",
"/resources/networks/41"
],
"password": "125504917100029",
"storage": [
"/resources/storage/58",
"/resources/storage/59",
"/resources/storage/60"
],
"type": "PowerVM",
"updated": 1255049245832,
"userid": "root"
}

PUT /resources/hypervisors/{id} example

Request JSON:


{
   "address": "https://newname.mycompany.com/sdk",
   "certified": "T",
   "cloud": "/resources/clouds/1",
   "created": 1245249680477,
   "currentmessage": "RM03106",
   "currentmessage_text": "Maintenance mode (must add to a cloud group to start)",
   "currentstatus": "RM01025",
   "currentstatus_text": "Maintenance mode",
   "desiredstatus": "RM01006",
   "desiredstatus_text": "Maintenance mode",
   "id": 5,
   "name": "new name",
   "networks": [
   ],
   "password": "new password",
   "storage": [
   ],
   "type": "ESX",
   "updated": 1245249680477,
   "userid": "newuserid"
}

Response JSON:

{
   "address": "https://newname.mycompany.com/sdk",
   "certified": "T",
   "cloud": "/resources/clouds/1",
   "created": 1245249680477,
   "currentmessage": "RM03106",
   "currentmessage_text": "Maintenance mode (must add to a cloud group to start)",
   "currentstatus": "RM01025",
   "currentstatus_text": "Maintenance mode",
   "desiredstatus": "RM01006",
   "desiredstatus_text": "Maintenance mode",
   "id": 5,
   "name": "new name",
   "networks": [
   ],
   "password": "124524969310837",
   "storage": [
   ],
   "type": "ESX",
   "updated": 1245249693109,
   "userid": "newuserid"
}