IM REST API

Optionally, IM Service can be accessed through a REST(ful) API. The port number and the security settings are controlled by the options listed in REST API.

In the following link you can follow the IM REST API in Swaggerhub: Swagger API.

Every HTTP request must be accompanied by the header AUTHORIZATION with the content of the Authorization File, but putting all the elements in one line using “\n” as separator. If the content cannot be parsed successfully, or the user and password are not valid, it is returned the HTTP error code 401. In case that Vault support has been configured (Vault Configuration) also a Bearer authorization header is supported, using the same access token to authenticate with the Vault server.

Next tables summaries the resources and the HTTP methods available.

HTTP method

/infrastructures

/infrastructures/<infId>

/infrastructures/<infId>/vms/<vmId>

GET

List the infrastructure IDs.
List the virtual machines
in the infrastructure infId
Get information associated to the
virtual machine vmId in infId.

POST

Create a new infrastructure
based on the RADL or TOSCA
posted.
Add or Remove virtual
machines based on the RADL
or TOSCA posted.
Modify the virtual machine based on
the RADL or TOSCA posted.

PUT

Import an infrastructure
from another IM instance

DELETE

Undeploy all the virtual
machines in the infrastructure.
Undeploy the virtual machine.

HTTP method

/infrastructures/<infId>/stop

/infrastructures/<infId>/start

/infrastructures/<infId>/reconfigure

PUT

Stop the infrastructure.
Start the infrastructure.
Reconfigure the infrastructure.

HTTP method

/infrastructures/<infId>/vms/<vmId>/stop

/infrastructures/<infId>/vms/<vmId>/start

/infrastructures/<infId>/vms/<vmId>/reboot

PUT

Stop the machine vmId in infId.
Start the machine vmId in infId.
Reboot the machine vmId in infId.

HTTP method

/infrastructures/<infId>/vms/<vmId>/disks/<diskNum>/snapshot

PUT

Create an snapshot of the disk diskNum of the
machine vmId in infId.

The error message returned by the service will depend on the Accept header of the request:

  • text/plain: (default option).

  • application/json: The request has a “Accept” header with value “application/json”. In this case the format will be:

    {
      "message": "Error message text",
      "code" : 400
     }
    
  • text/html: The request has a “Accept” with value to “text/html”.

GET http://imserver.com/infrastructures
Response Content-type:

text/uri-list or application/json

input fields:

filter (optional)

ok response:

200 OK

fail response:

401, 400

Return a list of URIs referencing the infrastructures associated to the IM user. In case of using a filter it will be used as a regular expression to search in the RADL or TOSCA used to create the infrastructure. The result is JSON format has the following format:

{
  "uri-list": [
     { "uri" : "http://server.com:8800/infrastructures/inf_id1" },
     { "uri" : "http://server.com:8800/infrastructures/inf_id2" }
   ]
}
POST http://imserver.com/infrastructures
body:

RADL or TOSCA document

body Content-type:

text/plain, application/json or text/yaml

input fields:

async (optional)

Response Content-type:

text/uri-list

ok response:

200 OK

fail response:

401, 400, 415

Create and configure an infrastructure with the requirements specified in the RADL (in plain RADL or in JSON formats) or TOSCA document of the body contents.

The async parameter is optional and is a flag to specify if the call will not wait the VMs to be created. Acceptable values: yes, no, true, false, 1 or 0. If not specified the flag is set to False.

If success, it is returned the URI of the new infrastructure. The result is JSON format has the following format:

{
  "uri" : "http://server.com:8800/infrastructures/inf_id
}
PUT http://imserver.com/infrastructures
body:

JSON data of the infrastructure

body Content-type:

application/json

Response Content-type:

text/uri-list

ok response:

200 OK

fail response:

401, 400, 415

Take control of the infrastructure serialized in in the body and return the ID associated in the server. (See GET /infrastructures/<infId>/data).

If success, it is returned the URI of the new infrastructure. The result is JSON format has the following format:

{
  "uri" : "http://server.com:8800/infrastructures/inf_id
}
GET http://imserver.com/infrastructures/<infId>
Response Content-type:

text/uri-list or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Return a list of URIs referencing the virtual machines associated to the infrastructure with ID infId. The result is JSON format has the following format:

{
  "uri-list": [
     { "uri" : "http://server.com:8800/infrastructures/inf_id/vms/0" },
     { "uri" : "http://server.com:8800/infrastructures/inf_id/vms/1" }
   ]
}
GET http://imserver.com/infrastructures/<infId>/<property_name>
Response Content-type:

text/plain or application/json

ok response:

200 OK

input fields:

headeronly (optional)

fail response:

401, 404, 400, 403

Return property property_name associated to the infrastructure with ID infId. It has the following properties::
outputs:

in case of TOSCA documents it will return a JSON object with the outputs of the TOSCA document.

contmsg:

a string with the contextualization message. In case of headeronly flag is set to ‘yes’, ‘true’ or ‘1’ only the initial part of the infrastructure contextualization log will be returned (without any VM contextualization log).

radl:

a string with the original specified RADL of the infrastructure.

tosca:

a string with the TOSCA representation of the infrastructure.

data:

a string with the JSOMN serialized data of the infrastructure. In case of delete flag is set to ‘yes’, ‘true’ or ‘1’ the data not only will be exported but also the infrastructure will be set deleted (the virtual infrastructure will not be modified).

authorization:

a list of strings with the current owners of the infrastructure.

state:

a JSON object with two elements:

state:

a string with the aggregated state of the infrastructure (see list of valid states in IM valid States).

vm_states:

a dict indexed with the VM ID and the value the VM state (see list of valid states in IM valid States).

The result is JSON format has the following format:

{
  ["radl"|"tosca"|"state"|"contmsg"|"outputs"|"data"|"authorization"]: <property_value>
}
POST http://imserver.com/infrastructures/<infId>/authorization
Response Content-type:

text/plain or application/json

body Content-type:

application/json

input fields:

overwrite (optional)

ok response:

200 OK

fail response:

401, 404, 400, 403

Change the authorization data of the infrastructure with ID infId. using the authorization data provided in the body call. The overwrite parameter is optional and is a flag to specify if the authorization data will be overwrited or will be appended. Acceptable values: yes, no, true, false, 1 or 0. If not specified the flag is set to True.

The body JSON format has the following format:

{
   "username": "new_username",
   "password": "new_password"
}

or:

{
   "token": "valid_oidc_access_token"
}
POST http://imserver.com/infrastructures/<infId>
body:

RADL or TOSCA document

body Content-type:

text/plain, application/json or text/yaml

input fields:

context (optional)

Response Content-type:

text/uri-list

ok response:

200 OK

fail response:

401, 403, 404, 400, 415

Add the resources specified in the body contents (in TOSCA, RADL plain or in JSON formats) to the infrastructure with ID infId. Using RADL the RADL restrictions are the same as in RPC-XML AddResource.

Using TOSCA as input this method can be used to add or remove resources depending on the number of resources specified in the new TOSCA document sent. If new nodes are added in the body compared with the last TOSCA sent to the IM, these new nodes will be added. For example an infrastructure has been created with this TOSCA document: tosca_create.yml it launches one DB server and one Web server. If this TOSCA document is sent as body of this POST function: tosca_add.yml, a new web server will be added as the number of web servers has been increased to two (count parameter of scalable capability). However if this document is sent after the node addition (the number of web servers will be two): tosca_remove.yml , a web server (the VM with the ID 2 as specified in the removal_list parameter) will be removed.

If success, it is returned a list of URIs of the new virtual machines. The context parameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. Acceptable values: yes, no, true, false, 1 or 0. If not specified the flag is set to True. The result is JSON format has the following format:

{
  "uri-list": [
     { "uri" : "http://server.com:8800/infrastructures/inf_id/vms/2" },
     { "uri" : "http://server.com:8800/infrastructures/inf_id/vms/3" }
   ]
}
PUT http://imserver.com/infrastructures/<infId>/stop
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Perform the stop action in all the virtual machines in the the infrastructure with ID infID. If the operation has been performed successfully the return value is an empty string.

PUT http://imserver.com/infrastructures/<infId>/start
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Perform the start action in all the virtual machines in the the infrastructure with ID infID. If the operation has been performed successfully the return value is an empty string.

PUT http://imserver.com/infrastructures/<infId>/reconfigure
body:

RADL document

body Content-type:

text/plain or application/json

input fields:

vm_list (optional)

Response Content-type:

text/plain

ok response:

200 OK

fail response:

401, 403, 404, 400, 415

Perform the reconfigure action in all the virtual machines in the the infrastructure with ID infID. It updates the configuration of the infrastructure as indicated in the body contents (in plain RADL or in JSON formats). The RADL restrictions are the same as in RPC-XML Reconfigure. If no RADL are specified, the contextualization process is stated again. The vm_list parameter is optional and is a coma separated list of IDs of the VMs to reconfigure. If not specified all the VMs will be reconfigured. If the operation has been performed successfully the return value is an empty string.

DELETE http://imserver.com/infrastructures/<infId>
input fields:

force (optional), async (optional)

Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Undeploy the virtual machines associated to the infrastructure with ID infId. If the operation has been performed successfully The force parameter is optional and is a flag to specify that the infra will be from the IM although not all resources are deleted. The return value is an empty string. If async is set to True the call will not wait the infrastructure to be deleted.

GET http://imserver.com/infrastructures/<infId>/vms/<vmId>
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Return information about the virtual machine with ID vmId associated to the infrastructure with ID infId. The returned string is in RADL format, either in plain RADL or in JSON formats. See more the details of the output in GetVMInfo. The result is JSON format has the following format:

{
  "radl": "<radl_in_json>"
}
PUT http://imserver.com/infrastructures/<infId>/vms/<vmId>
body:

RADL document

body Content-type:

text/plain or application/json

Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400, 415

Change the features of the virtual machine with ID vmId in the infrastructure with with ID infId, specified by the RADL radl. Return then information about the nodified virtual machine. The returned string is in RADL format, either in plain RADL or in JSON formats. See more the details of the output in GetVMInfo. The result is JSON format has the following format:

{
  "radl": "<radl_in_json>"
}
GET http://imserver.com/infrastructures/<infId>/vms/<vmId>/<property_name>
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Return property property_name from to the virtual machine with ID vmId associated to the infrastructure with ID infId. It also has one special property contmsg that provides a string with the contextualization message of this VM. The result is JSON format has the following format:

{
  "<property_name>": "<property_value>"
}
DELETE http://imserver.com/infrastructures/<infId>/vms/<vmId>
input fields:

context (optional)

Response Content-type:

text/plain

ok response:

200 OK

fail response:

401, 403, 404, 400

Undeploy the virtual machine with ID vmId associated to the infrastructure with ID infId. If vmId is a comma separated list of VM IDs, all the VMs of this list will be undeployed. The context parameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. Acceptable values: yes, no, true, false, 1 or 0. If not specified the flag is set to True. If the operation has been performed successfully the return value is an empty string.

PUT http://imserver.com/infrastructures/<infId>/vms/<vmId>/start
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Perform the start action in the virtual machine with ID vmId associated to the infrastructure with ID infId. If the operation has been performed successfully the return value is an empty string.

PUT http://imserver.com/infrastructures/<infId>/vms/<vmId>/stop
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Perform the stop action in the virtual machine with ID vmId associated to the infrastructure with ID infId. If the operation has been performed successfully the return value is an empty string.

PUT http://imserver.com/infrastructures/<infId>/vms/<vmId>/reboot
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

401, 403, 404, 400

Perform the reboot action in the virtual machine with ID vmId associated to the infrastructure with ID infId. If the operation has been performed successfully the return value is an empty string.

GET http://imserver.com/version
Response Content-type:

text/plain or application/json

ok response:

200 OK

fail response:

400

Return the version of the IM service. The result is JSON format has the following format:

{
  "version": "1.4.4"
}
PUT http://imserver.com/infrastructures/<infId>/vms/<vmId>/disks/<diskNum>/snapshot
Response Content-type:

text/plain or application/json

ok response:

200 OK

input fields:

image_name (mandatory), auto_delete (optional)

fail response:

401, 403, 404, 400

Create a snapshot of the specified diskNum in the VM vmId of the infrastructure with ID infId.

The autoDelete flag specifies that the snapshot will be deleted when the infrastructure is destroyed (default value false). If the operation has been performed successfully the return value is the image url of the new created image in IM format (see disk.<diskId>.image.url format in RADL).

GET http://imserver.com/clouds/<cloudId>/images
Response Content-type:

application/json

ok response:

200 OK

input fields:

filters (optional)

fail response:

401, 400

Return a list of URIs referencing the images available in the specified cloud provider cloudId. The optional filters parameter enables filterin the list of images. It is a comma separated list of keypair values (key1=val1,key2=value2). This field is cloud provider specific (e.g. region=region_name for Amazon EC2, GCE or Azure). The id cloudId is relative to the id field in the AUTHORIZATION header. The result is JSON format has the following format:

{
“images”:
[
{

“uri” : “ost://hostname/image-id1”, “name” : “Image Name1”

}, {

“uri” : “ost://hostname/image-id2”, “name” : “Image Name2”

}

]

}

GET http://imserver.com/clouds/<cloudId>/quotas
Response Content-type:

application/json

ok response:

200 OK

fail response:

401, 400

Get the used and available resources in the specified cloud provider cloudId. The id cloudId is relative to the id field in the AUTHORIZATION header. The result is JSON format has the following format:

{
  "quotas": {
     "cores": {"used": 1, "limit": 10},
     "ram": {"used": 1, "limit": 10},
     "instances": {"used": 1, "limit": 10},
     "floating_ips": {"used": 1, "limit": 10},
     "security_groups": {"used": 1, "limit": 10}
  }
}