Chapter 3. Examples

This section provides a collection of examples of using the REST API to interact with resources in a Red Hat CloudForms environment.

3.1. General Queries

This section introduces a number of general examples of how to use the REST API to query resources, and return information about resources and events.

3.1.1. Queries

Query all virtual machines: 

GET /api/vms

Query a specific virtual machine: 

GET /api/vms/1386

Query all virtual machines, but return only the name and vendor: 

GET /api/vms?expand=resources&attributes=name,vendor

Query all virtual machines named sample*, and return the name and vendor: 

GET /api/vms?expand=resources&attributes=name,vendor&filter[]="name='sample%'"

Query all virtual machines, but only return the first 500 results: 

GET /api/vms?offset=0&limit=500

Query all virtual machines, but return the second 500 results: 

GET /api/vms?offset=500&limit=500

Query the first 1000 virtual machines named test*, get the name, vendor, and guid, and sort by name in ascending order: 

GET /api/vms?offset=0&limit=1000&filter[]="name='test%'"&expand=resources&attributes=name,vendor,guid&sort_by=name&sort_order=asc

Query services tagged for the finance department: 

GET /api/services?by_tag=/department/finance

Get the details of tags for the first service: 

GET /api/services/1/tags?expand=resources

Get the details of the first service catalog and related details on the assigned service templates: 

GET /api/service_catalogs/1?expand=service_templates
GET /api/service_templates/25/service_requests?expand=resources,request_tasks

Get a specific provision request with expanded details on the associated provision request tasks: 

GET /api/provision_requests/120?expand=tasks

Query infrastructure provider information: 

GET /api/providers/120?expand=resources,lans,networks,folders

3.1.2. Paging Queries

This series of requests shows paging queries and the expected responses for each subsequent page.

3.1.2.1. Request:

GET /api/vms?offset=0&limit=500
    &sort_order=asc&sort_by=name
    &expand=resources&attributes=name

3.1.2.2. Response:

{
  "name": "vms",
  "count": 1912,
  "subcount": 500,
  "resources": [
    {
      "href": "https://hostname/api/vms/176",
      "id": 176,
      "name": "53 Zone1"
    },
    ...
    {
      "href": "https://hostname/api/vms/1575",
      "id": 1575,
      "name": "VmEmpty-3de98f0f-c6f3-4f8b-a932-554713a61067"
    }
  ],
  "actions": [
  ]
}

3.1.2.3. Request:

GET /api/vms?offset=500&limit=500
    &sort_order=asc&sort_by=name
    &expand=resources&attributes=name

3.1.2.4. Response:

{
  "name": "vms",
  "count": 1912,
  "subcount": 500,
  "resources": [
    {
      "href": "https://hostname/api/vms/1574",
      "id": 1574,
      "name": "VmEmpty-3e13ff43-6907-4a22-8f95-58aeb1bffa0b"
    },
    ...
    {
      "href": "https://hostname/api/vms/1076",
      "id": 1076,
      "name": "VmEmpty-9a885181-7771-4f91-9805-245c7606d833"
    }
  ],
  "actions": [
  ]
}

3.1.2.5. Request:

GET /api/vms?offset=1000&limit=500
    &sort_order=asc&sort_by=name
    &expand=resources&attributes=name

3.1.2.6. Response:

{
  "name": "vms",
  "count": 1912,
  "subcount": 500,
  "resources": [
    {
      "href": "https://hostname/api/vms/1074",
      "id": 1074,
      "name": "VmEmpty-9ab9e101-92b0-4b6b-864e-e196538da8a8"
    },
    ...
    {
      "href": "https://hostname/api/vms/575",
      "id": 575,
      "name": "VmEmpty-f251f135-01c8-4d44-b8e1-37b30844a9dd"
    }
  ],
  "actions": [
  ]
}

3.1.2.7. Request:

GET /api/vms?offset=1500&limit=500
    &sort_order=asc&sort_by=name
    &expand=resources&attributes=name

3.1.2.8. Response:

{
  "name": "vms",
  "count": 1912,
  "subcount": 412,
  "resources": [
    {
      "href": "https://hostname/api/vms/574",
      "id": 574,
      "name": "VmEmpty-f28912f3-b096-487f-9763-97b39b67364b"
    },
    ...
    {
      "href": "https://hostname/api/vms/1907",
      "id": 1907,
      "name": "yy_vm"
    }
  ],
  "actions": [
  ]
}
Note

In this last request, the subcount was less than the requested page size, thus denoting the last page of data being returned.

3.1.3. Querying a Delete Task

3.1.3.1. Request:

GET /api/tasks/625

3.1.3.2. Response:

{
  "href": "https://hostname/api/tasks/625",
  "id": 625,
  "name": "Provider id:106 name:'rhevm102' deleting",
  "state": "Finished",
  "status": "Ok",
  "message": "Task completed successfully",
  "userid": "admin",
  "created_on": "2015-05-06T14:02:26Z",
  "updated_on": "2015-05-06T14:02:32Z"
}

3.2. Service Catalogs

This section provides examples of how to interact with service catalogs.

3.2.1. Adding a Sample Service Catalog

3.2.1.1. Request:

POST /api/service_catalogs
{
   "action" : "create",
   "resource" : {
        "name" : "Sample Service Catalog",
        "description" : "Description of Sample Service Catalog",
        "service_templates" : [
          { "href" : "https://hostname/api/service_templates/3" },
          { "href" : "https://hostname/api/service_templates/4" }
        ]
   }
}

3.2.1.2. Response:

{
  "results": [
    {
      "id": 7,
      "name": "Sample Service Catalog",
      "description": "Description of Sample Service Catalog"
    }
  ]
}

3.2.2. Adding Multiple Service Catalogs

3.2.2.1. Request:

POST /api/service_catalogs
{
   "action" : "create",
   "resources" : [
      {
        "name" : "First Sample Service Catalog",
        "description" : "Description of First Sample Service Catalog",
        "service_templates" : [
          { "href" : "https://hostname/api/service_templates/1" },
          { "href" : "https://hostname/api/service_templates/2" }
        ]
      },
      {
        "name" : "Second Sample Service Catalog",
        "description" : "Description of Second Sample Service Catalog",
        "service_templates" : [
          { "href" : "https://hostname/api/service_templates/3" },
          { "href" : "https://hostname/api/service_templates/4" }
        ]
      },
      {
        "name" : "Third Sample Service Catalog",
        "description" : "Description of Third Sample Service Catalog",
        "service_templates" : [
          { "href" : "https://hostname/api/service_templates/5" },
          { "href" : "https://hostname/api/service_templates/6" }
        ]
      }
  ]
}

3.2.2.2. Response:

{
  "results": [
    {
      "id": 8,
      "name": "First Sample Service Catalog",
      "description": "Description of First Sample Service Catalog"
    },
    {
      "id": 9,
      "name": "Second Sample Service Catalog",
      "description": "Description of Second Sample Service Catalog"
    },
    {
      "id": 10,
      "name": "Third Sample Service Catalog",
      "description": "Description of Third Sample Service Catalog"
    }
  ]
}

3.2.3. Assigning Service Templates to Service Catalogs

3.2.3.1. Request:

POST /api/service_catalogs/6/service_templates
{
  "action" : "assign",
  "resources" : [
    { "href" : "https://hostname/api/service_templates/5" },
    { "href" : "https://hostname/api/service_templates/1" }
  ]
}

3.2.3.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Service Template id:5 name:'template5'",
      "service_template_id": 5,
      "service_template_href": "https://hostname/api/service_templates/5",
      "href": "https://hostname/api/service_catalogs/6"
    },
    {
      "success": false,
      "message": "Service Template 1 is currently assigned to Service Catalog 3",
      "service_template_id": 1,
      "service_template_href": "https://hostname/api/service_templates/1",
      "href": "https://hostname/api/service_catalogs/6"
    }
  ]
}

3.2.4. Editing a Service Catalog

3.2.4.1. Request:

POST /api/service_catalog/7
{
   "action" : "edit",
   "resource" : {
      "description" : "Updated Description of the Seventh Service Catalog"
   }
}

3.2.4.2. Response:

{
  "href": "https://hostname/api/service_catalogs/7",
  "id": 7,
  "name": "Sample Service Catalog",
  "description": "Updated Description of the Seventh Service Catalog",
  "service_templates": {
    "count": 1,
    "resources": [
      {
        "href": "https://hostname/api/service_catalogs/7/service_templates/3"
      }
    ]
  }
}

3.2.5. Editing Multiple Service Catalogs

3.2.5.1. Request:

POST /api/service_catalogs
{
   "action" : "edit",
   "resources" : [
     {
       "href" : "https://hostname/api/service_catalogs/3",
       "description" : "Updated Description for Third Service Catalog"
     },
     {
       "href" : "https://hostname/api/service_catalogs/6",
       "description" : "Updated Description for Sixth Service Catalog"
     }
   ]
}

3.2.5.2. Response:

{
  "results": [
    {
      "id": 3,
      "name": "Service Catalog B Added from REST API",
      "description": "Updated Description for Third Service Catalog"
    },
    {
      "id": 6,
      "name": "Service Catalog E Added from REST API",
      "description": "Updated Description for Sixth Service Catalog"
    }
  ]
}

3.2.6. Ordering a Single Service from a Service Catalog

3.2.6.1. Request:

POST /api/service_catalogs/1/service_templates
{
  "action" : "order",
  "resource" : {
    "href" : "https://hostname/api/service_templates/3",
    "option_0_vm_target_name" : "test-vm-0001",
    "option_0_vm_target_hostname" : "test-vm-0001"
  }
}

3.2.6.2. Response:

{
  results: [
    {
      "approval_state": "pending_approval",
      "created_on": "2014-07-02T19:28:12Z",
      "description": "Provisioning Service [aws-ubuntu-api] from [aws-ubuntu-api]",
      "destination_id": null,
      "destination_type": null,
      "fulfilled_on": null,
      "id": 13,
      "message": "Service_Template_Provisioning - Request Created",
      "options": {
        "dialog": {
          "dialog_option_0_vm_target_name" : "test-vm-0001",
          "dialog_option_0_vm_target_hostname" : "test-vm-0001"
        }
    }
    "request_state": "pending",
    "request_type": "clone_to_service",
    "requester_id": 1,
    "requester_name": "Administrator",
    "source_id": 6,
    "source_type": "ServiceTemplate",
    "status": "Ok",
    "updated_on": "2014-07-02T19:28:12Z",
    "userid": "admin"
    }
  ]
}

3.2.7. Ordering Multiple Services from a Service Catalog

3.2.7.1. Request:

POST /api/service_catalogs/2/service_templates
{
  "action" : "order",
  "resources" : [
    {
      "href" : "https://hostname/api/service_templates/3",
      "option_1_vm_target_name" : "sample-vm-1201",
      "option_2_vm_target_hostname" : "sample-vm-1201"
    },
    {
      "href" : "https://hostname/api/service_templates/3",
      "option_1_vm_target_name" : "sample-vm-1202",
      "option_2_vm_target_hostname" : "sample-vm-1202"
    },
    {
      "href" : "https://hostname/api/service_templates/4",
      "option_1_vm_target_name" : "dev-vm1",
      "option_2_vm_target_hostname" : "dev-vm1",
      "option_3_vm_memory" : '16384'
    },
  ]
}

3.2.7.2. Response:

{
  results: [
    {
      "approval_state": "pending_approval",
      "created_on": "2014-07-02T19:28:12Z",
      "description": "Provisioning Service [sample-vm-1201] from [sample-vm-1201]",
      "destination_id": null,
      "destination_type": null,
      "fulfilled_on": null,
      "id": 13,
      "message": "Service_Template_Provisioning - Request Created",
      "options": {
        "dialog": {
          "dialog_option_0_vm_target_name" : "test-vm-0001",
          "dialog_option_0_vm_target_hostname" : "test-vm-0001"
        }
    }
    "request_state": "pending",
    "request_type": "clone_to_service",
    "requester_id": 1,
    "requester_name": "Administrator",
    "source_id": 6,
    "source_type": "ServiceTemplate",
    "status": "Ok",
    "updated_on": "2014-07-02T19:28:12Z",
    "userid": "admin"
    },
    {
      "approval_state": "pending_approval",
      "created_on": "2014-07-02T19:28:12Z",
      "description": "Provisioning Service [sample-vm-1202] from [sample-vm-1202]",
      "destination_id": null,
      "destination_type": null,
      "fulfilled_on": null,
      "id": 13,
      "message": "Service_Template_Provisioning - Request Created",
      "options": {
        "dialog": {
          "dialog_option_0_vm_target_name" : "test-vm-0001",
          "dialog_option_0_vm_target_hostname" : "test-vm-0001"
        }
    }
    "request_state": "pending",
    "request_type": "clone_to_service",
    "requester_id": 1,
    "requester_name": "Administrator",
    "source_id": 6,
    "source_type": "ServiceTemplate",
    "status": "Ok",
    "updated_on": "2014-07-02T19:28:12Z",
    "userid": "admin"
    },
    {
      "approval_state": "pending_approval",
      "created_on": "2014-07-02T19:28:12Z",
      "description": "Provisioning Service [sample-vm-1201] from [sample-vm-1201]",
      "destination_id": null,
      "destination_type": null,
      "fulfilled_on": null,
      "id": 13,
      "message": "Service_Template_Provisioning - Request Created",
      "options": {
        "dialog": {
          "dialog_option_0_vm_target_name" : "test-vm-0001",
          "dialog_option_0_vm_target_hostname" : "test-vm-0001"
        }
    }
    "request_state": "pending",
    "request_type": "clone_to_service",
    "requester_id": 1,
    "requester_name": "Administrator",
    "source_id": 6,
    "source_type": "ServiceTemplate",
    "status": "Ok",
    "updated_on": "2014-07-02T19:28:12Z",
    "userid": "admin"
    }
  ]
}

3.2.8. Unassigning Service Templates from a Service Catalog

3.2.8.1. Request:

POST /api/service_catalogs/6/service_templates
{
  "action" : "unassign",
  "resources" : [
    { "href" : "https://hostname/api/service_templates/1" },
    { "href" : "https://hostname/api/service_templates/5" },
    { "href" : "https://hostname/api/service_templates/8" }
  ]
}

3.2.8.2. Response:

{
  "results": [
    {
      "success": false,
      "message": "Service Template 1 is not currently assigned to Service Catalog 3",
      "service_template_id": 1,
      "service_template_href": "https://hostname/api/service_templates/1",
      "href": "https://hostname/api/service_catalogs/6"
    },
    {
      "success": true,
      "message": "Unassigning Service Template id:5 name:'template5'",
      "service_template_id": 5,
      "service_template_href": "https://hostname/api/service_templates/5",
      "href": "https://hostname/api/service_catalogs/6"
    },
    {
      "success": false,
      "message": "Couldn't find ServiceTemplate with id=8",
      "href": "https://hostname/api/service_catalogs/6"
    }
  ]
}

3.2.9. Deleting Multiple Service Catalogs

3.2.9.1. Request:

POST /api/service_catalogs
{
  "action" : "delete",
  "resources" : [
    { "href" : "https://hostname/api/service_catalogs/8"  },
    { "href" : "https://hostname/api/service_catalogs/9"  },
    { "href" : "https://hostname/api/service_catalogs/10" }
  ]
}

3.2.9.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "service_catalogs id: 8 deleting",
      "href": "https://hostname/api/service_catalogs/8"
    },
    {
      "success": true,
      "message": "service_catalogs id: 9 deleting",
      "href": "https://hostname/api/service_catalogs/9"
    },
    {
      "success": true,
      "message": "service_catalogs id: 10 deleting",
      "href": "https://hostname/api/service_catalogs/10"
    }
  ]
}

3.3. Tags

This section provides examples of how to interact with tags.

3.3.1. Assigning Tags to a Service

3.3.1.1. Request:

POST /api/services/101/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "location", "name" : "ny" },
    { "category" : "department", "name" : "finance" },
    { "category" : "environment", "name" : "dev" }
  ]
}

3.3.1.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/services/101",
      "tag_category": "location",
      "tag_name": "ny"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/services/101",
      "tag_category": "department",
      "tag_name": "finance"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'dev'",
      "href": "https://hostname/api/services/101",
      "tag_category": "environment",
      "tag_name": "dev"
    }
  ]
}

3.3.2. Assigning Tags by Name to a Service

3.3.2.1. Request:

POST /api/services/101/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "/department/finance" },
    { "name" : "/location/ny" }
  ]
}

3.3.2.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/services/101",
      "tag_category": "department",
      "tag_name": "finance"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/services/101",
      "tag_category": "location",
      "tag_name": "ny"
    }
  ]
}

3.3.3. Assigning Tags by Reference to a Service

3.3.3.1. Request:

POST /api/services/101/tags
{
  "action" : "assign",
  "resources" : [
    { "href" : "https://hostname/api/services/1/tags/49" }
  ]
}

3.3.3.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/services/101",
      "tag_category": "department",
      "tag_name": "finance",
      "tag_href": "https://hostname/api/tags/49"
    }
  ]
}

3.3.4. Assigning Tags to a Service Template

3.3.4.1. Request:

POST /api/service_templates/1/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "location", "name" : "ny" },
    { "category" : "department", "name" : "finance" }
  ]
}

3.3.4.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/service_templates/1",
      "tag_category": "location",
      "tag_name": "ny"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/service_templates/1",
      "tag_category": "department",
      "tag_name": "finance"
    }
  ]
}

3.3.5. Assigning Tags to a Virtual Machine

3.3.5.1. Request:

POST /api/vms/101/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "/department/finance" },
    { "name" : "/location/ny" }
  ]
}

3.3.5.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/vms/101",
      "tag_category": "location",
      "tag_name": "ny"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/vms/101",
      "tag_category": "department",
      "tag_name": "finance"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'dev'",
      "href": "https://hostname/api/vms/101",
      "tag_category": "environment",
      "tag_name": "dev"
    }
  ]
}

3.3.6. Assigning Tags by Name to a Virtual Machine

3.3.6.1. Request:

POST /api/vms/101/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "/department/finance" },
    { "name" : "/location/ny" }
  ]
}

3.3.6.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/vms/101",
      "tag_category": "department",
      "tag_name": "finance"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/vms/101",
      "tag_category": "location",
      "tag_name": "ny"
    }
  ]
}

3.3.7. Assigning Tags by Reference to a Virtual Machine

3.3.7.1. Request:

POST /api/vms/101/tags
{
  "action" : "assign",
  "resources" : [
    { "href" : "https://hostname/api/vms/1/tags/49" }
  ]
}

3.3.7.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/vms/101",
      "tag_category": "department",
      "tag_name": "finance",
      "tag_href": "https://hostname/api/tags/49"
    }
  ]
}

3.3.8. Unassigning Tags from a Service

3.3.8.1. Request:

POST /api/services/101/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "department", "name" : "finance" },
    { "category" : "environment", "name" : "dev" }
  ]
}

3.3.8.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/services/101",
      "tag_category": "department",
      "tag_name": "finance"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'environment' name:'dev'",
      "href": "https://hostname/api/services/101",
      "tag_category": "environment",
      "tag_name": "dev"
    }
  ]
}

3.3.9. Unassigning a Tag by Name from a Service

3.3.9.1. Request:

POST /api/services/101/tags
{
  "action" : "unassign",
  "resources" : [
    { "name" : "/managed/department/finance" }
  ]
}

3.3.9.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/services/101",
      "tag_category": "department",
      "tag_name": "finance"
    }
  ]
}

3.3.10. Unassigning a Tag by Reference from a Service

3.3.10.1. Request:

POST /api/services/101/tags
{
  "action" : "unassign",
  "resources" : [
    { "href" : "tags/49" }
  ]
}

3.3.10.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/services/101",
      "tag_category": "department",
      "tag_name": "finance",
      "tag_href": "https://hostname/api/tags/49"
    }
  ]
}

3.3.11. Unassigning Tags from a Service Template

3.3.11.1. Request:

POST /api/service_templates/1/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "location", "name" : "ny" },
    { "category" : "department", "name" : "finance" }
  ]
}

3.3.11.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/service_templates/1",
      "tag_category": "location",
      "tag_name": "ny"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'finance'",
      "href": "https://hostname/api/service_templates/1",
      "tag_category": "department",
      "tag_name": "finance"
    }
  ]
}

3.3.12. Assigning Tags to Cloud Networks

3.3.12.1. Request:

POST /api/cloud_networks/223/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "location", "name" : "chicago" },
    { "category" : "department", "name" : "support" },
    { "category" : "environment", "name" : "test" }
  ]
}

3.3.12.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'chicago'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "location",
      "tag_name": "chicago"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'support'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "department",
      "tag_name": "support"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.13. Assigning Tags by Name to Cloud Networks

3.3.13.1. Request:

POST /api/cloud_networks/223/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "location/chicago" },
    { "name" : "department/support" },
    { "name" : "environment/test" }
  ]
}

3.3.13.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'chicago'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "location",
      "tag_name": "chicago"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'support'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "department",
      "tag_name": "support"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.14. Unassigning Tags on Cloud Networks

3.3.14.1. Request:

POST /api/cloud_networks/223/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "location", "name" : "chicago" },
    { "category" : "department", "name" : "support" },
    { "category" : "environment", "name" : "test" }
  ]
}

3.3.14.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'location' name:'chicago'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "location",
      "tag_name": "chicago"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'support'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "department",
      "tag_name": "support"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/cloud_networks/223",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.15. Assigning Tags to Cloud Subnets

3.3.15.1. Request:

POST /api/cloud_subnets/7/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "location", "name" : "london" },
    { "category" : "department", "name" : "marketing" },
    { "category" : "environment", "name" : "dev" }
  ]
}

3.3.15.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'ny'",
      "href": "https://hostname/api/cloud_subnets/7",
      "tag_category": "location",
      "tag_name": "ny"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'marketing'",
      "href": "https://hostname/api/cloud_subnets/7",
      "tag_category": "department",
      "tag_name": "marketing"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'dev'",
      "href": "https://hostname/api/cloud_subnets/7",
      "tag_category": "environment",
      "tag_name": "dev"
    }
  ]
}

3.3.16. Assigning Tags by Name to Cloud Subnets

3.3.16.1. Request:

POST /api/cloud_subnets/7/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "location/internal" },
    { "name" : "department/marketing" },
    { "name" : "environment/dev" }
  ]
}

3.3.16.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'internal'",
      "href": "https://hostname/api/cloud_subnets/30",
      "tag_category": "location",
      "tag_name": "internal"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'marketing'",
      "href": "https://hostname/api/cloud_subnets/30",
      "tag_category": "department",
      "tag_name": "marketing"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'dev'",
      "href": "https://hostname/api/cloud_subnets/30",
      "tag_category": "environment",
      "tag_name": "dev"
    }
  ]
}

3.3.17. Unassigning Tags on Cloud Subnets

3.3.17.1. Request:

POST /api/cloud_subnets/7/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "location", "name" : "london" },
    { "category" : "department", "name" : "marketing" },
    { "category" : "environment", "name" : "dev" }
  ]
}

3.3.17.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'location' name:'london'",
      "href": "https://hostname/api/cloud_subnets/7",
      "tag_category": "location",
      "tag_name": "london"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'marketing'",
      "href": "https://hostname/api/cloud_subnets/7",
      "tag_category": "department",
      "tag_name": "marketing"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'environment' name:'dev'",
      "href": "https://hostname/api/cloud_subnets/7",
      "tag_category": "environment",
      "tag_name": "dev"
    }
  ]
}

3.3.18. Assigning Tags to Availability Zones

3.3.18.1. Request:

POST /api/availability_zones/14/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "location", "name" : "london" },
    { "category" : "department", "name" : "engineering" },
    { "category" : "environment", "name" : "test" }
  ]
}

3.3.18.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'london'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "location",
      "tag_name": "ny"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'engineering'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "department",
      "tag_name": "engineering"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.19. Assigning Tags by Name to Availability Zones

3.3.19.1. Request:

POST /api/availability_zones/14/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "location/london" },
    { "name" : "department/engineering" },
    { "name" : "environment/test" }
  ]
}

3.3.19.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'location' name:'london'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "location",
      "tag_name": "london"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'department' name:'engineering'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "department",
      "tag_name": "engineering"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.20. Unassigning Tags on Availability Zones

3.3.20.1. Request:

POST /api/availability_zones/14/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "location", "name" : "london" },
    { "category" : "department", "name" : "engineering" },
    { "category" : "environment", "name" : "test" }
  ]
}

3.3.20.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'location' name:'london'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "location",
      "tag_name": "london"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'department' name:'engineering'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "department",
      "tag_name": "engineering"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/availability_zones/14",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.21. Assigning Tags to Flavors

3.3.21.1. Request:

POST /api/flavors/223/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "owner", "name" : "production linux team" },
    { "category" : "service level", "name" : "gold" }
  ]
}

3.3.21.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'owner' name:'production linux team'",
      "href": "https://hostname/api/flavors/223",
      "tag_category": "owner",
      "tag_name": "production linux team"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'service level' name:'gold'",
      "href": "https://hostname/api/flavors/223",
      "tag_category": "service level",
      "tag_name": "gold"
    }
  ]
}

3.3.22. Assigning Tags by Name to Flavors

3.3.22.1. Request:

POST /api/flavors/223/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "owner/production linux team" },
    { "name" : "service level/gold" }
  ]
}

3.3.22.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'owner' name:'production linux team'",
      "href": "https://hostname/api/flavors/223",
      "tag_category": "owner",
      "tag_name": "production linux team"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'service level' name:'gold'",
      "href": "https://hostname/api/flavors/223",
      "tag_category": "service level",
      "tag_name": "gold"
    }
  ]
}

3.3.23. Unassigning Tags on Flavors

3.3.23.1. Request:

POST /api/flavors/223/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "owner", "name" : "production linux team" },
    { "category" : "service level", "name" : "gold" }
  ]
}

3.3.23.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'owner' name:'production linux team'",
      "href": "https://hostname/api/flavors/223",
      "tag_category": "owner",
      "tag_name": "production linux team"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'owner' name:'gold'",
      "href": "https://hostname/api/flavors/223",
      "tag_category": "service level",
      "tag_name": "gold"
    }
  ]
}

3.3.24. Assigning Tags to Network Routers

3.3.24.1. Request:

POST /api/network_routers/400/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "network location", "name" : "cloud" },
    { "category" : "environment", "name" : "production" }
  ]
}

3.3.24.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'network location' name:'cloud'",
      "href": "https://hostname/api/network_routers/400",
      "tag_category": "network location",
      "tag_name": "cloud"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'production'",
      "href": "https://hostname/api/network_routers/400",
      "tag_category": "environment",
      "tag_name": "production"
    }
  ]
}

3.3.25. Assigning Tags by Name to Network Routers

3.3.25.1. Request:

POST /api/cloud_networks/400/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "network location/cloud" },
    { "name" : "environment/production" }
  ]
}

3.3.25.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'network location' name:'cloud'",
      "href": "https://hostname/api/cloud_networks/400",
      "tag_category": "network location",
      "tag_name": "cloud"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'production'",
      "href": "https://hostname/api/cloud_networks/400",
      "tag_category": "environment",
      "tag_name": "production"
    }
  ]
}

3.3.26. Unassigning Tags on Network Routers

3.3.26.1. Request:

POST /api/network_routers/400/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "network location", "name" : "cloud" },
    { "category" : "environment", "name" : "production" }
  ]
}

3.3.26.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'network location' name:'cloud'",
      "href": "https://hostname/api/network_routers/400",
      "tag_category": "network location",
      "tag_name": "cloud"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'environment' name:'production'",
      "href": "https://hostname/api/network_routers/400",
      "tag_category": "environment",
      "tag_name": "production"
    }
  ]
}

3.3.27. Assigning Tags to Security Groups

3.3.27.1. Request:

POST /api/security_groups/30/tags
{
  "action" : "assign",
  "resources" : [
    { "category" : "network location", "name" : "internal" },
    { "category" : "owner", "name" : "windows 2008 test team" },
    { "category" : "environment", "name" : "test" }
  ]
}

3.3.27.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'network location' name:'internal'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "network location",
      "tag_name": "internal"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'owner' name:'windows 2008 test team'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "owner",
      "tag_name": "windows 2008 test team"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.28. Assigning Tags by Name to Security Groups

3.3.28.1. Request:

POST /api/security_groups/30/tags
{
  "action" : "assign",
  "resources" : [
    { "name" : "network location/internal" },
    { "name" : "owner/windows 2008 test team" },
    { "name" : "environment/test" }
  ]
}

3.3.28.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Assigning Tag: category:'network location' name:'internal'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "network location",
      "tag_name": "internal"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'owner' name:'windows 2008 test team'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "owner",
      "tag_name": "windows 2008 test team"
    },
    {
      "success": true,
      "message": "Assigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.3.29. Unassigning Tags on Security Groups

3.3.29.1. Request:

POST /api/security_groups/30/tags
{
  "action" : "unassign",
  "resources" : [
    { "category" : "network location", "name" : "internal" },
    { "category" : "owner", "name" : "windows 2008 test team" },
    { "category" : "environment", "name" : "test" }
  ]
}

3.3.29.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "Unassigning Tag: category:'network location' name:'internal'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "network location",
      "tag_name": "internal"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'owner' name:'windows 2008 test team'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "owner",
      "tag_name": "windows 2008 test team"
    },
    {
      "success": true,
      "message": "Unassigning Tag: category:'environment' name:'test'",
      "href": "https://hostname/api/security_groups/30",
      "tag_category": "environment",
      "tag_name": "test"
    }
  ]
}

3.4. Automation Requests

This section provides examples of how to interact with automation requests.

3.4.1. Triggering a Single Automation Request

With automation requests:
  • version defaults to 1.1 if not specified.
  • user_name defaults to the REST API authenticated user if not specified.

3.4.1.1. Request:

POST /api/automation_requests
{
  "version" : "1.1",
  "uri_parts" : {
    "namespace" : "System",
    "class" : "Request",
    "instance" : "InspectME",
    "message" : "create"
  },
  "parameters" : {
    "var1" : "xxxxx",
    "var2" : "yyyyy",
    "var3" : 1024,
    "var4" : true,
    "var5" : "last value"
  },
  "requester" : {
    "user_name" : "admin",
    "auto_approve" : true
  }
}

Optionally, the action-based request format is also supported:

3.4.1.2. Request:

POST /api/automation_requests
{
  "action" : "create",
  "resource" : {
    "version" : "1.1",
    "uri_parts" : {
      "namespace" : "System",
      "class" : "Request",
      "instance" : "InspectME",
      "message" : "create"
    },
    "parameters" : {
      "var1" : "xxxxx",
      "var2" : "yyyyy",
      "var3" : 1024,
      "var4" : true,
      "var5" : "last value"
    },
    "requester" : {
      "user_name" : "admin",
      "auto_approve" : true
    }
  }
}

3.4.1.3. Response:

{
  "results": [
    {
      "id": 12,
      "description": "Automation Task",
      "approval_state": "approved",
      "type": "AutomationRequest",
      "created_on": "2015-04-16T21:49:55Z",
      "updated_on": "2015-04-16T21:49:55Z",
      "requester_id": 1,
      "requester_name": "Administrator",
      "request_type": "automation",
      "request_state": "pending",
      "status": "Ok",
      "options": {
        "message": "create",
        "namespace": "System",
        "class_name": "Request",
        "instance_name": "InspectME",
        "user_id": 1,
        "attrs": {
          "var1": "xxxxx",
          "var2": "yyyyy",
          "var3": 1024,
          "var4": true,
          "var5": "last value",
          "userid": "admin"
        }
      },
      "userid": "admin"
    }
  ]
}

3.4.2. Triggering Multiple Automation Requests

With automation requests:

  • version defaults to 1.1 if not specified.
  • user_name defaults to the REST API authenticated user if not specified.

3.4.2.1. Request:

POST /api/automation_requests
{
  "action" : "create",
  "resources" : [
    {
      "version" : "1.1",
      "uri_parts" :  {
        "namespace" : "System",
        "class" : "Request",
        "instance" : "InspectME",
        "message" : "create"
      },
      "parameters" : {
        "vm_name" : "test_1",
        "var2" : "yyyyy",
        "var3" : 1024,
        "var4" : true,
        "var5" : "last value"
      },
      "requester" :  {
        "user_name" : "jdoe",
        "auto_approve" : true
      }
    },
    {
      "uri_parts" :  {
        "namespace" : "System",
        "class" : "Request",
        "instance" : "InspectME",
        "message" : "create"
      },
      "parameters" : {
        "vm_name" : "test_2",
        "vm_memory" : 1024,
        "memory_limit" : 16384
      },
      "requester" :  {
        "auto_approve" : true
      }
    },
    {
      "uri_parts" :  {
        "namespace" : "System",
        "class" : "Request",
        "instance" : "InspectME",
        "message" : "create"
      },
      "parameters" : {
        "vm_name" : "test_3",
        "vm_memory" : 2048,
        "memory_limit" : 16384
      },
      "requester" :  {
        "auto_approve" : true
      }
    },
    {
      "uri_parts" :  {
        "namespace" : "System",
        "class" : "Request",
        "instance" : "InspectME",
        "message" : "create"
      },
      "parameters" : {
        "vm_name" : "test_4",
        "vm_memory" : 4096,
        "memory_limit" : 16384
      },
      "requester" :  {
        "auto_approve" : true
      }
    }
  ]
}

3.4.2.2. Response:

{
  "results": [
    {
      "id": 14,
      "description": "Automation Task",
      "approval_state": "approved",
      "type": "AutomationRequest",
      "created_on": "2015-04-16T21:59:42Z",
      "updated_on": "2015-04-16T21:59:42Z",
      "requester_id": 13,
      "requester_name": "aab",
      "request_type": "automation",
      "request_state": "pending",
      "status": "Ok",
      "options": {
        "message": "create",
        "namespace": "System",
        "class_name": "Request",
        "instance_name": "InspectME",
        "user_id": 13,
        "attrs": {
          "vm_name": "test_1",
          "var2": "yyyyy",
          "var3": 1024,
          "var4": true,
          "var5": "last value",
          "userid": "aab"
        }
      },
      "userid": "aab"
    },
    {
      "id": 15,
      "description": "Automation Task",
      "approval_state": "approved",
      "type": "AutomationRequest",
      "created_on": "2015-04-16T21:59:42Z",
      "updated_on": "2015-04-16T21:59:42Z",
      "requester_id": 1,
      "requester_name": "Administrator",
      "request_type": "automation",
      "request_state": "pending",
      "status": "Ok",
      "options": {
        "message": "create",
        "namespace": "System",
        "class_name": "Request",
        "instance_name": "InspectME",
        "user_id": 1,
        "attrs": {
          "vm_name": "test_2",
          "vm_memory": 1024,
          "memory_limit": 16384,
          "userid": "admin"
        }
      },
      "userid": "admin"
    },
    {
      "id": 16,
      "description": "Automation Task",
      "approval_state": "approved",
      "type": "AutomationRequest",
      "created_on": "2015-04-16T21:59:42Z",
      "updated_on": "2015-04-16T21:59:42Z",
      "requester_id": 1,
      "requester_name": "Administrator",
      "request_type": "automation",
      "request_state": "pending",
      "status": "Ok",
      "options": {
        "message": "create",
        "namespace": "System",
        "class_name": "Request",
        "instance_name": "InspectME",
        "user_id": 1,
        "attrs": {
          "vm_name": "test_3",
          "vm_memory": 2048,
          "memory_limit": 16384,
          "userid": "admin"
        }
      },
      "userid": "admin"
    },
    {
      "id": 17,
      "description": "Automation Task",
      "approval_state": "approved",
      "type": "AutomationRequest",
      "created_on": "2015-04-16T21:59:42Z",
      "updated_on": "2015-04-16T21:59:42Z",
      "requester_id": 1,
      "requester_name": "Administrator",
      "request_type": "automation",
      "request_state": "pending",
      "status": "Ok",
      "options": {
        "message": "create",
        "namespace": "System",
        "class_name": "Request",
        "instance_name": "InspectME",
        "user_id": 1,
        "attrs": {
          "vm_name": "test_4",
          "vm_memory": 4096,
          "memory_limit": 16384,
          "userid": "admin"
        }
      },
      "userid": "admin"
    }
  ]
}

3.5. Provisioning Requests

This section provides examples of how to interact with provisioning requests.

3.5.1. Triggering a Single Provision Request

With provisioning requests:

  • version defaults to 1.1 if not specified.
  • user_name defaults to the REST API authenticated user if not specified.

3.5.1.1. Request:

Provisioning requests are made available via the following entrypoint, either by specifying a create action or by posting the request directly to /api/provision_requests: 

POST /api/provision_requests
{
  "version" : "1.1",
  "template_fields" : {
    "guid" : "afe6e8a0-89fd-11e3-b6ac-b8e85646e742"
  },
  "vm_fields" : {
    "number_of_cpus" : 1,
    "vm_name" : "aab_rest_vm1",
    "vm_memory" : "1024",
    "vlan" : "rhevm"
  },
  "requester" : {
    "user_name" : "jdoe",
    "owner_first_name" : "John",
    "owner_last_name" : "Doe",
    "owner_email" : "jdoe@sample.com",
    "auto_approve" : true
  },
  "tags" : {
    "network_location" : "Internal",
    "cc" : "001"
  },
  "additional_values" : {
    "request_id" : "1001"
  },
  "ems_custom_attributes" : { },
  "miq_custom_attributes" : { }
}

Optionally, the action-based request format is also supported:

3.5.1.2. Request:

POST /api/provision_requests
{
  "action" : "create",
  "resource" : {
    "version" : "1.1",
      "template_fields" : {
        "guid" : "afe6e8a0-89fd-11e3-b6ac-b8e85646e742"
      },
      "vm_fields" : {
        "number_of_cpus" : 1,
        "vm_name" : "aab_rest_vm1",
        "vm_memory" : "1024",
        "vlan" : "rhevm"
      },
      "requester" : {
        "user_name" : "jdoe",
        "owner_first_name" : "John",
        "owner_last_name" : "Doe",
        "owner_email" : "jdoe@sample.com",
        "auto_approve" : true
      },
      "tags" : {
        "network_location" : "Internal",
        "cc" : "001"
      },
      "additional_values" : {
        "request_id" : "1001"
      },
      "ems_custom_attributes" : { },
      "miq_custom_attributes" : { }
  }
}

3.5.1.3. Response:

{
  "results": [
    {
      "id": 18,
      "description": "Provision from [bd-clone-template] to [aab_rest_vm1]",
      "approval_state": "pending_approval",
      "type": "MiqProvisionRequest",
      "created_on": "2015-05-08T17:42:55Z",
      "updated_on": "2015-05-08T17:42:55Z",
      "requester_id": 1,
      "requester_name": "Administrator",
      "request_type": "template",
      "request_state": "pending",
      "message": "VM Provisioning - Request Created",
      "status": "Ok",
      "options": {
        "use_pre_dialog": false,
        "request_type": "template",
        "miq_request_dialog_name": "miq_provision_redhat_dialogs_template",
        "owner_first_name": "John",
        "owner_last_name": "Doe",
        "owner_email": "jdoe@sample.com",
        "vm_tags": [
          62,
          58
        ],
        "addr_mode": [
          "static",
          "Static"
        ],
        "placement_cluster_name": [
          null,
          null
        ],
        "cluster_filter": [
          null,
          null
        ],
        "placement_auto": [
          true,
          1
        ],
        "placement_dc_name": [
          null,
          null
        ],
        "number_of_vms": [
          1,
          "1"
        ],
        "src_vm_id": [
          1947,
          "bd-clone-template"
        ],
        "provision_type": [
          "native_clone",
          "Native Clone"
        ],
        "linked_clone": [
          null,
          null
        ],
        "vm_name": "aab_rest_vm1",
        "pxe_server_id": [
          null,
          null
        ],
        "schedule_type": [
          "immediately",
          "Immediately on Approval"
        ],
        "vm_auto_start": [
          true,
          1
        ],
        "schedule_time": "2015-05-09T13:42:54-04:00",
        "retirement": [
          0,
          "Indefinite"
        ],
        "retirement_warn": [
          604800,
          "1 Week"
        ],
        "stateless": [
          false,
          0
        ],
        "vlan": [
          "rhevm",
          "rhevm"
        ],
        "disk_format": [
          "default",
          "Default"
        ],
        "number_of_sockets": [
          1,
          "1"
        ],
        "cores_per_socket": [
          1,
          "1"
        ],
        "vm_memory": [
          "1024",
          "1024"
        ],
        "network_adapters": [
          1,
          "1"
        ],
        "placement_host_name": [
          null,
          null
        ],
        "placement_ds_name": [
          null,
          null
        ],
        "src_vm_nics": [

        ],
        "src_vm_lans": [

        ],
        "customize_enabled": [
          "enabled"
        ],
        "src_ems_id": [
          105,
          "rhevm230"
        ],
        "auto_approve": false,
        "ws_values": {
          "request_id": "1001"
        },
        "ws_ems_custom_attributes": {
        },
        "ws_miq_custom_attributes": {
        }
      },
      "userid": "jdoe",
      "source_id": 1947,
      "source_type": "VmOrTemplate"
    }
  ]
}

3.5.2. Triggering Multiple Provision Requests

With provisioning requests:

  • version defaults to 1.1 if not specified.
  • user_name defaults to the REST API authenticated user if not specified.

3.5.2.1. Request:

POST /api/provision_requests
{
  "action" : "create",
  "resources" : [
    {
      "version" : "1.1",
      "template_fields" : { "guid" : "afe6e8a0-89fd-11e3-b6ac-b8e85646e742" },
      "vm_fields" : {
        "vm_name" : "jdoe_rest_vm1",
        "number_of_cpus" : 1,
        "vm_memory" : "1024",
        "vlan" : "nic1"
      },
      "requester" : {
        "user_name" : "jdoe",
        "owner_first_name" : "John",
        "owner_last_name" : "Doe",
        "owner_email" : "jdoe@sample.com",
        "auto_approve" : true
      },
      "tags" : {
        "network_location" : "Internal",
        "cc" : "001"
      },
      "additional_values" : { "request_id" : "1001" },
      "ems_custom_attributes" : { },
      "miq_custom_attributes" : { }
    },
    {
      "template_fields" : { "guid" : "afe6e8a0-89fd-11e3-b6ac-b8e85646e742" },
      "vm_fields" : {
        "vm_name" : "jdoe_rest_vm2",
        "number_of_cpus" : 1,
        "vm_memory" : "2048",
        "vlan" : "nic1"
      },
      "requester" : {
        "owner_first_name" : "John",
        "owner_last_name" : "Doe",
        "owner_email" : "jdoe@sample.com",
        "auto_approve" : true
      },
      "tags" : {
        "network_location" : "Internal",
        "cc" : "001"
      },
      "additional_values" : { "request_id" : "1002" }
    },
    {
      "template_fields" : { "guid" : "afe6e8a0-89fd-11e3-b6ac-b8e85646e742" },
      "vm_fields" : {
        "vm_name" : "jdoe_rest_vm3",
        "number_of_cpus" : 1,
        "vm_memory" : "4096",
        "vlan" : "nic1"
      },
      "requester" : {
        "owner_first_name" : "John",
        "owner_last_name" : "Doe",
        "owner_email" : "jdoe@sample.com",
        "auto_approve" : true
      },
      "tags" : {
        "network_location" : "Internal",
        "cc" : "001"
      },
      "additional_values" : { "request_id" : "1003" }
    }
  ]
}

3.5.2.2. Response:

{
  "results": [
    {
      "id": 19,
      "description": "Provision from [bd-clone-template] to [aab_rest_vm1]",
      "approval_state": "pending_approval",
      "type": "MiqProvisionRequest",
      "created_on": "2015-05-08T18:25:25Z",
      "updated_on": "2015-05-08T18:25:26Z",
      "requester_id": 1,
      "requester_name": "jdoe",
      "request_type": "template",
      "request_state": "pending",
      "message": "VM Provisioning - Request Created",
      "status": "Ok",
      "options": {
        "use_pre_dialog": false,
        "request_type": "template",
        "miq_request_dialog_name": "miq_provision_redhat_dialogs_template",
        "owner_first_name": "John",
        "owner_last_name": "Doe",
        "owner_email": "jdoe@sample.com",
        "vm_tags": [
          62,
          58
        ],
        "addr_mode": [
          "static",
          "Static"
        ],
        "placement_cluster_name": [
          null,
          null
        ],
        "cluster_filter": [
          null,
          null
        ],
        "placement_auto": [
          true,
          1
        ],
        "placement_dc_name": [
          null,
          null
        ],
        "number_of_vms": [
          1,
          "1"
        ],
        "src_vm_id": [
          1947,
          "bd-clone-template"
        ],
        "provision_type": [
          "native_clone",
          "Native Clone"
        ],
        "linked_clone": [
          null,
          null
        ],
        "vm_name": "aab_rest_vm1",
        "pxe_server_id": [
          null,
          null
        ],
        "schedule_type": [
          "immediately",
          "Immediately on Approval"
        ],
        "vm_auto_start": [
          true,
          1
        ],
        "schedule_time": "2015-05-09T14:25:25-04:00",
        "retirement": [
          0,
          "Indefinite"
        ],
        "retirement_warn": [
          604800,
          "1 Week"
        ],
        "stateless": [
          false,
          0
        ],
        "vlan": [
          "rhevm",
          "rhevm"
        ],
        "disk_format": [
          "default",
          "Default"
        ],
        "number_of_sockets": [
          1,
          "1"
        ],
        "cores_per_socket": [
          1,
          "1"
        ],
        "vm_memory": [
          "1024",
          "1024"
        ],
        "network_adapters": [
          1,
          "1"
        ],
        "placement_host_name": [
          null,
          null
        ],
        "placement_ds_name": [
          null,
          null
        ],
        "src_vm_nics": [

        ],
        "src_vm_lans": [

        ],
        "customize_enabled": [
          "enabled"
        ],
        "src_ems_id": [
          105,
          "rhevm230"
        ],
        "auto_approve": false,
        "ws_values": {
          "request_id": "1001"
        },
        "ws_ems_custom_attributes": {
        },
        "ws_miq_custom_attributes": {
        }
      },
      "userid": "jdoe",
      "source_id": 1947,
      "source_type": "VmOrTemplate"
    },
    {
      "id": 20,
      "description": "Provision from [bd-clone-template] to [aab_rest_vm2]",
      "approval_state": "pending_approval",
      "type": "MiqProvisionRequest",
      "created_on": "2015-05-08T18:25:28Z",
      "updated_on": "2015-05-08T18:25:29Z",
      "requester_id": 1,
      "requester_name": "jdoe",
      "request_type": "template",
      "request_state": "pending",
      "message": "VM Provisioning - Request Created",
      "status": "Ok",
      "options": {
        "use_pre_dialog": false,
        "request_type": "template",
        "miq_request_dialog_name": "miq_provision_redhat_dialogs_template",
        "owner_first_name": "John",
        "owner_last_name": "Doe",
        "owner_email": "jdoe@sample.com",
        "vm_tags": [
          62,
          58
        ],
        "addr_mode": [
          "static",
          "Static"
        ],
        "placement_cluster_name": [
          null,
          null
        ],
        "cluster_filter": [
          null,
          null
        ],
        "placement_auto": [
          true,
          1
        ],
        "placement_dc_name": [
          null,
          null
        ],
        "number_of_vms": [
          1,
          "1"
        ],
        "src_vm_id": [
          1947,
          "bd-clone-template"
        ],
        "provision_type": [
          "native_clone",
          "Native Clone"
        ],
        "linked_clone": [
          null,
          null
        ],
        "vm_name": "aab_rest_vm2",
        "pxe_server_id": [
          null,
          null
        ],
        "schedule_type": [
          "immediately",
          "Immediately on Approval"
        ],
        "vm_auto_start": [
          true,
          1
        ],
        "schedule_time": "2015-05-09T14:25:28-04:00",
        "retirement": [
          0,
          "Indefinite"
        ],
        "retirement_warn": [
          604800,
          "1 Week"
        ],
        "stateless": [
          false,
          0
        ],
        "vlan": [
          "rhevm",
          "rhevm"
        ],
        "disk_format": [
          "default",
          "Default"
        ],
        "number_of_sockets": [
          1,
          "1"
        ],
        "cores_per_socket": [
          1,
          "1"
        ],
        "vm_memory": [
          "1024",
          "1024"
        ],
        "network_adapters": [
          1,
          "1"
        ],
        "placement_host_name": [
          null,
          null
        ],
        "placement_ds_name": [
          null,
          null
        ],
        "src_vm_nics": [

        ],
        "src_vm_lans": [

        ],
        "customize_enabled": [
          "enabled"
        ],
        "src_ems_id": [
          105,
          "rhevm230"
        ],
        "auto_approve": false,
        "ws_values": {
          "request_id": "1001"
        },
        "ws_ems_custom_attributes": {
        },
        "ws_miq_custom_attributes": {
        }
      },
      "userid": "jdoe",
      "source_id": 1947,
      "source_type": "VmOrTemplate"
    },
    {
      "id": 21,
      "description": "Provision from [bd-clone-template] to [aab_rest_vm3]",
      "approval_state": "pending_approval",
      "type": "MiqProvisionRequest",
      "created_on": "2015-05-08T18:25:32Z",
      "updated_on": "2015-05-08T18:25:32Z",
      "requester_id": 1,
      "requester_name": "jdoe",
      "request_type": "template",
      "request_state": "pending",
      "message": "VM Provisioning - Request Created",
      "status": "Ok",
      "options": {
        "use_pre_dialog": false,
        "request_type": "template",
        "miq_request_dialog_name": "miq_provision_redhat_dialogs_template",
        "owner_first_name": "John",
        "owner_last_name": "Doe",
        "owner_email": "jdoe@sample.com",
        "vm_tags": [
          62,
          58
        ],
        "addr_mode": [
          "static",
          "Static"
        ],
        "placement_cluster_name": [
          null,
          null
        ],
        "cluster_filter": [
          null,
          null
        ],
        "placement_auto": [
          true,
          1
        ],
        "placement_dc_name": [
          null,
          null
        ],
        "number_of_vms": [
          1,
          "1"
        ],
        "src_vm_id": [
          1947,
          "bd-clone-template"
        ],
        "provision_type": [
          "native_clone",
          "Native Clone"
        ],
        "linked_clone": [
          null,
          null
        ],
        "vm_name": "aab_rest_vm3",
        "pxe_server_id": [
          null,
          null
        ],
        "schedule_type": [
          "immediately",
          "Immediately on Approval"
        ],
        "vm_auto_start": [
          true,
          1
        ],
        "schedule_time": "2015-05-09T14:25:31-04:00",
        "retirement": [
          0,
          "Indefinite"
        ],
        "retirement_warn": [
          604800,
          "1 Week"
        ],
        "stateless": [
          false,
          0
        ],
        "vlan": [
          "rhevm",
          "rhevm"
        ],
        "disk_format": [
          "default",
          "Default"
        ],
        "number_of_sockets": [
          1,
          "1"
        ],
        "cores_per_socket": [
          1,
          "1"
        ],
        "vm_memory": [
          "1024",
          "1024"
        ],
        "network_adapters": [
          1,
          "1"
        ],
        "placement_host_name": [
          null,
          null
        ],
        "placement_ds_name": [
          null,
          null
        ],
        "src_vm_nics": [

        ],
        "src_vm_lans": [

        ],
        "customize_enabled": [
          "enabled"
        ],
        "src_ems_id": [
          105,
          "rhevm230"
        ],
        "auto_approve": false,
        "ws_values": {
          "request_id": "1001"
        },
        "ws_ems_custom_attributes": {
        },
        "ws_miq_custom_attributes": {
        }
      },
      "userid": "jdoe",
      "source_id": 1947,
      "source_type": "VmOrTemplate"
    }
  ]
}

3.5.3. Monitoring Request

Once a provisioning request is created, the response result will include the queryable provision request itself, for example: /api/provision_requests/:id

3.5.3.1. Response:

{
  "results": [
    {
      "id": 3068,
      "description": "Provision from [template1] to [###]",
      "approval_state": "pending_approval",
      "type": "MiqProvisionRequest",
      "created_on": "2015-04-14T17:36:30Z",
      "updated_on": "2015-04-14T17:36:30Z",
      "requester_id": 88913,
      "requester_name": "API User",
      "request_type": "template",
      "request_state": "pending",
      "message": "VM Provisioning - Request Created",
      "status": "Ok"
      "options": {
        "use_pre_dialog": false,
        "request_type": "template",
        "miq_request_dialog_name": "miq_provision_dialogs",
        "src_vm_id": [
          109996,
          "template1"
        ],
        "src_vm_nics": [],
        "src_vm_lans": [],
        "src_ems_id": [
          59136,
          "ems_0000000000002"
        ],
        "placement_auto": [
          true,
          1
        ],
        "vm_tags": [],
        "ws_values": {
        },
        "ws_ems_custom_attributes": {
        },
        "ws_miq_custom_attributes": {
        },
        "tags": {
        }
      },
      "userid": "admin",
      "source_id": 109996,
      "source_type": "VmOrTemplate"
    }
  ]
}

In the above example, the request can be queried periodically until the request_state reaches the finished state with: 

GET /api/provision_requests/3068
Note

The requests tasks of a provisioning request can also be queried by expanding the request_tasks subcollection as follows: 

GET /api/provision_requests/:id?expand=request_tasks

An alias tasks is also defined for the above subcollection: 

GET /api/provision_requests/:id?expand=tasks

For a list of available attributes, see the Provisioning Request Attributes section.

3.5.4. Placement of Environmental Variables in Provisioning Requests

Pass environment values directly through the vm_fields attribute group of a provisioning request by first adding "placement_auto":"false" to the hash.

Note

Once "placement_auto:"false" has been added, you must pass values for all the required fields on the Environment tab.

The example request displays how the vm_fields attribute group should appear when passing environment values.

3.5.4.1. Request:

Provisioning requests are made available via the following entrypoint, either by specifying a create action or by posting the request directly to /api/provision_requests: 

POST /api/provision_requests
"vm_fields" : {
  "vm_name" : "aab_rest_vm1",
  "placement_auto": "false",
  "placement_availability_zone": "2",
  "cloud_network": "2",
  "cloud_subnet": "3",
  "security_groups": "64",
  "instance_type": "2",
},

3.6. Providers

This section provides examples of how to interact with providers.

3.6.1. Creating a Provider

3.6.1.1. Request:

POST /api/providers
{
  "type"      : "ManageIQ::Providers::Redhat::InfraManager",
  "name"      : "rhevm101",
  "hostname"  : "rhevm101",
  "ipaddress" : "100.200.300.101",
  "credentials" : {
    "userid"    : "admin_account",
    "password"  : "admin_password"
  }
}

3.6.1.2. Response:

{
  "results": [
    {
      "id": 105,
      "name": "rhevm101",
      "hostname": "rhevm101",
      "ipaddress": "100.200.300.101",
      "created_on": "2015-05-05T15:47:41Z",
      "updated_on": "2015-05-05T15:47:41Z",
      "guid": "10360312-f33e-11e4-86c7-b8e85646e742",
      "zone_id": 1,
      "type": "ManageIQ::Providers::Redhat::InfraManager"
    }
  ]
}

3.6.2. Creating a Provider with Compound Credentials

3.6.2.1. Request:

POST /api/providers
{
  "type"      : "ManageIQ::Providers::Redhat::InfraManager",
  "name"      : "rhevm102",
  "hostname"  : "rhevm102",
  "ipaddress" : "100.200.300.102",
  "credentials" : [
    {
      "userid"    : "default_userid",
      "password"  : "default_password"
    },
    {
      "userid"    : "metrics_userid",
      "password"  : "metrics_password",
      "auth_type" : "metrics"
    }
  ]
}

3.6.2.2. Response:

{
  "results": [
    {
      "id": 106,
      "name": "rhevm102",
      "hostname": "rhevm102",
      "ipaddress": "100.200.300.102",
      "created_on": "2015-05-05T15:57:44Z",
      "updated_on": "2015-05-05T15:57:44Z",
      "guid": "acbd610e-f3f6-11e4-aaba-b8e85646e742",
      "zone_id": 1,
      "type": "ManageIQ::Providers::Redhat::InfraManager"
    }
  ]
}

3.6.3. Refreshing a Provider

3.6.3.1. Request:

POST /api/providers/105
{
  "action" : "refresh"
}

3.6.3.2. Response:

{
  "success": true,
  "message": "Provider id:105 name:'rhevm105' refreshing",
  "href": "https://hostname/api/providers/105"
}

3.6.4. Updating a Provider

3.6.4.1. Request:

POST /api/providers/106
{
  "action"    : "edit",
  "ipaddress" : "100.200.300.112",
  "credentials" : [
    {
      "userid"    : "updated_metrics_userid",
      "password"  : "updated_metrics_password",
      "auth_type" : "metrics"
    }
  ]
}

3.6.4.2. Response:

{
  "href": "https://hostname/api/providers/106",
  "id": 106,
  "name": "rhevm102",
  "hostname": "rhevm102",
  "ipaddress": "100.200.300.112",
  "created_on": "2015-05-06T13:49:11Z",
  "updated_on": "2015-05-06T13:53:06Z",
  "guid": "acbd610e-f3f6-11e4-aaba-b8e85646e742",
  "zone_id": 1,
  "type": "ManageIQ::Providers::Redhat::InfraManager"
}

3.6.5. Deleting a Provider

3.6.5.1. Deleting a Single Provider

3.6.6. Request:

DELETE /api/provider/105

Or via the delete action as follows: 

POST /api/provider/105
{
  "action" : "delete"
}

3.6.7. Response:

{
  "success": true,
  "message": "Provider id:106 name:'rhevm102' deleting",
  "task_id": 625,
  "task_href": "https://hostname/api/tasks/625",
  "href": "https://hostname/api/providers/106"
}
Note

Delete actions are done asynchronously as it can take a while to complete. The delete task can be queried as follows:

3.6.8. Request:

GET /api/tasks/625

3.6.9. Response:

{
  "href": "https://hostname/api/tasks/625",
  "id": 625,
  "name": "Provider id:106 name:'rhevm102' deleting",
  "state": "Finished",
  "status": "Ok",
  "message": "Task completed successfully",
  "userid": "admin",
  "created_on": "2015-05-06T14:02:26Z",
  "updated_on": "2015-05-06T14:02:32Z"
}

3.6.9.1. Deleting Multiple Providers

3.6.10. Request:

POST /api/providers
{
  "action" : "delete",
  "resources" : [
    { "href" : "https://hostname/api/providers/107" },
    { "href" : "https://hostname/api/providers/108" }
  ]
}

3.6.11. Response:

{
  "results": [
    {
      "success": true,
      "message": "Provider id:107 name:'rhevm102' deleting",
      "task_id": 626,
      "task_href": "https://hostname/api/tasks/626",
      "href": "https://hostname/api/providers/107"
    },
    {
      "success": true,
      "message": "Provider id:108 name:'rhevm103' deleting",
      "task_id": 627,
      "task_href": "https://hostname/api/tasks/627",
      "href": "https://hostname/api/providers/108"
    }
  ]
}

3.7. Services

This section provides examples of how to interact with services.

3.7.1. Editing a Service

3.7.1.1. Request:

POST /api/services/101
{
  "action" : "edit",
  "resource" : {
    "name" : "service_101",
    "description" : "This is an updated description for service 101"
  }
}

3.7.1.2. Response:

{
  "href": "https://hostname/api/services/101",
  "id": 101,
  "name": "service_101",
  "description": "This is an updated description for the service 101",
  "guid": "4a8f96de-a1a6-11e4-9f8d-b8e85646e742",
  "options": {
  },
  "created_at": "2015-01-21T19:47:11Z",
  "updated_at": "2015-04-16T22:17:15Z"
}

3.7.2. Editing Multiple Services

3.7.2.1. Request:

POST /api/services
{
  "action" : "edit",
  "resources" : [
    {
      "href" : "https://hostname/api/services/81",
      "description" : "This is an updated description for service 81"
    },
    {
      "href" : "https://hostname/api/services/82",
      "description" : "This is an updated description for service 82"
    }
  ]
}

3.7.2.2. Response:

{
  "results": [
    {
      "id": 81,
      "name": "api_gen_A_81",
      "description": "This is an updated description for service 81",
      "guid": "eb6daaf8-7c9b-11e4-8a3a-b8e85646e742",
      "options": {
      },
      "created_at": "2014-12-05T16:29:43Z",
      "updated_at": "2015-04-16T22:43:37Z"
    },
    {
      "id": 82,
      "name": "api_gen_A_82",
      "description": "This is an updated description for service 82",
      "guid": "eb6de400-7c9b-11e4-8a3a-b8e85646e742",
      "options": {
      },
      "created_at": "2014-12-05T16:29:43Z",
      "updated_at": "2015-04-16T22:43:37Z"
    }
  ]
}

3.7.3. Editing a Resource with the PATCH Method

Supported attribute actions for PATCH include add, edit and remove.

3.7.3.1. Request:

PATCH /api/services/90
[
  { "action" : "edit", "path" : "name", "value" : "updated_service_90" },
  { "action" : "remove", "path" : "description"}
]

3.7.3.2. Response:

{
  "href": "https://hostname/api/services/90",
  "id": 90,
  "name": "updated_service_90",
  "guid": "eb6fc61c-7c9b-11e4-8a3a-b8e85646e742",
  "options": {
  },
  "created_at": "2014-12-05T16:29:43Z",
  "updated_at": "2015-04-16T22:38:57Z"
}
Note

Note that the description attribute is no longer defined for this service.

3.7.4. Editing a Service with the PUT Method

3.7.4.1. Request:

PUT /api/services/90
{
  "name" : "new_service_90",
  "description" : "This is a new description for service 90"
}

3.7.4.2. Response:

{
  "href": "https://hostname/api/services/90",
  "id": 90,
  "name": "new_service_90",
  "description": "This is a new description for service 90",
  "guid": "eb6fc61c-7c9b-11e4-8a3a-b8e85646e742",
  "options": {
  },
  "created_at": "2014-12-05T16:29:43Z",
  "updated_at": "2015-04-16T22:41:37Z"
}

3.7.5. Retiring a Service Immediately

3.7.5.1. Request:

POST /api/services
{
  "action" : "request_retire",
  "resource" : { "href" : "https://hostname/api/services/35" }
}

3.7.5.2. Response:

{
  "results" : [
    {
      "href": "https://hostname/api/services/95",
      "id": 95,
      "name": "sample_service_95",
      "description": "Description for sample_service_95",
      "guid": "eb713538-7c9b-11e4-8a3a-b8e85646e742",
      "options": {
      },
      "created_at": "2014-12-05T16:29:43Z",
      "updated_at": "2015-05-08T19:32:00Z"
    }
  ]
}

Alternatively, this can be done by targeting the service directly: 

POST /api/services/95
{
  "action" : "request_retire"
}

3.7.5.3. Response:

{
  "href": "https://hostname/api/services/95",
  "id": 95,
  "name": "sample_service_95",
  "description": "Description for sample_service_95",
  "guid": "eb713538-7c9b-11e4-8a3a-b8e85646e742",
  "options": {
  },
  "created_at": "2014-12-05T16:29:43Z",
  "updated_at": "2015-05-08T19:32:00Z"
}

3.7.6. Retiring a Service at a Future Time

3.7.6.1. Request:

POST /api/services/93
{
  "action" : "request_retire",
  "resource" : { "date" : "10/31/2015", "warn" : "7"  }
}

3.7.6.2. Response:

{
  "href": "https://hostname/api/services/93",
  "id": 93,
  "name": "sample_service_93",
  "description": "Description for sample_service_93",
  "guid": "eb709e02-7c9b-11e4-8a3a-b8e85646e742",
  "options": {
  },
  "created_at": "2014-12-05T16:29:43Z",
  "updated_at": "2015-05-08T19:40:19Z",
  "retired": false,
  "retires_on": "2015-10-30",
  "retirement_warn": 7
}

3.7.7. Retiring Multiple Services

3.7.7.1. Request:

POST /api/services
{
  "action" : "request_retire",
  "resources" : [
      { "href" : "https://hostname/api/services/100" },
      { "href" : "https://hostname/api/services/101", "date" : "11/01/2015", "warn" : "4" },
      { "href" : "https://hostname/api/services/102", "date" : "11/02/2015", "warn" : "4" }
  ]
}

3.7.7.2. Response:

{
  "results": [
    {
      "id": 100,
      "name": "cloud_service_100",
      "description": "Description for cloud_service_100",
      "guid": "eb725f94-7c9b-11e4-8a3a-b8e85646e742",
      "options": {
      },
      "created_at": "2014-12-05T16:29:43Z",
      "updated_at": "2015-05-08T19:46:11Z"
    },
    {
      "id": 101,
      "name": "cloud_service_101",
      "description": "Description for cloud_service_101",
      "guid": "4a8f96de-a1a6-11e4-9f8d-b8e85646e742",
      "options": {
      },
      "created_at": "2015-01-21T19:47:11Z",
      "updated_at": "2015-05-08T19:46:19Z",
      "retired": false,
      "retires_on": "2015-11-01",
      "retirement_warn": 4
    },
    {
      "id": 102,
      "name": "cloud_service_102",
      "description": "Description for cloud_service_102",
      "guid": "e2da0cb0-e47e-11e4-a47f-b8e85646e742",
      "options": {
      },
      "created_at": "2015-04-16T21:23:55Z",
      "updated_at": "2015-05-08T19:46:19Z",
      "retired": false,
      "retires_on": "2015-11-02",
      "retirement_warn": 3
    }
  ]
}

3.7.8. Deleting Services

3.7.8.1. Request:

POST /api/services
{
  "action" : "delete",
  "resources" : [
    { "href" : "https://hostname/api/services/97" },
    { "href" : "https://hostname/api/services/98" },
    { "href" : "https://hostname/api/services/99" }
  ]
}

3.7.8.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "services id: 97 deleting",
      "href": "https://hostname/api/services/97"
    },
    {
      "success": true,
      "message": "services id: 98 deleting",
      "href": "https://hostname/api/services/98"
    },
    {
      "success": true,
      "message": "services id: 99 deleting",
      "href": "https://hostname/api/services/99"
    }
  ]
}

3.8. Virtual Machines

This section provides examples of how to interact with virtual machines.

3.8.1. Provisioning a Virtual Machine Using Cloud-init

3.8.1.1. Request:

POST api/provision_requests/
{"version"=>"1.1",
 "template_fields"=>
  {"guid"=>"1dbfed74-1c8b-4535-9f1e-c654a5456805",
   "name"=>"template_name",
   "request_type"=>"template"},
 "vm_fields"=>
  {"customization_template_id"=>10000000000000,
   "addr_mode"=>"static",
   "sysprep_enabled"=>"fields",
   "placement_auto"=>true,
   "number_of_vms"=>1,
   "provision_type"=>"native_clone",
   "vm_name"=>"name_of_vm_to_provision",
   "vm_auto_start"=>true,
   "retirement"=>0,
   "retirement_warn"=>604800,
   "vlan"=>"9af50e0c-b277-422a-a5c3-11e158d21fa8",
   "disk_format"=>"default",
   "number_of_sockets"=>1,
   "cores_per_socket"=>1,
   "vm_memory"=>"2048",
   "memory_reserve"=>341,
   "memory_limit"=>8192,
   "network_adapters"=>1},
 "requester"=>{"owner_email"=>"test@testing.com"},
 "tags"=>{},
 "additional_values"=>nil,
 "ems_custom_attributes"=>nil,
 "miq_custom_attributes"=>nil}

Following are some possible cases where the VLAN field is not set correctly, which can lead to a validation failure: 

Provision failed for the following reasons:\n'Network/Virtual NIC Profile ID or Profile Name (Network Name)' is required.

  1. When providing VNIC profile ID:

    1. vnic_profile_id does not belong to the expected cluster (should match the VNIC profile ID of the network taken from RHV based on template’s cluster assigned network)
    2. Non-existent VNIC profile ID (should be available under RHV, i.e.: https:/<RHV FQDN>/ovirt-engine/api/vnicprofiles)

  2. When providing: “profile name (network name)”:

    1. Non-existent network name
    2. Wrong format (missing space before the first bracket: “profile_name(network_name)”)
    3. Use Network name that was used in V3 instead of: “profile_name (network_name)”

Table 3.1. Examples of incorrect VLAN value:

VLAN valueResult

“vlan": "1dbfed74-1c8b-4535-9f1e-c654a5456805"

Failed, no such ID

"vlan": "aaa (aaa)"

Failed, no such VNIC profile/network

"vlan": "ovirtmgmt(ovirtmgmt)"

Failed, invalid format

"vlan": "0000000a-000a-000a-000a-000000000398"

Failed, VNIC profile ID of other cluster

"vlan": "ovirtmgmt"

Failed, not supported by v4

Table 3.2. Examples of correct VLAN value:

VLAN valueResult

"vlan": "654281a3-db89-4718-ae43-9466b81eb001"

Passed, valid VNIC profile ID

"vlan": "ovirtmgmt (ovirtmgmt)"

Passed, supported format

3.8.2. Scanning a Virtual Machine

3.8.2.1. Request:

POST /api/vms/1922
{
  "action": "scan"
}

3.8.2.2. Response:

{
  "success": true,
  "message": "VM id:1922 name:'aab_test_vm' scanning",
  "task_id": 618,
  "task_href": "https://hostname/api/tasks/618",
  "href": "https://hostname/api/vms/1922"
}

Optionally, to query the status of the scan:

3.8.2.3. Request:

GET /api/tasks/618

3.8.2.4. Response:

{
  "href": "https://hostname/api/tasks/618",
  "id": 618,
  "name": "VM id:1922 name:'aab_test_vm' scanning",
  "state": "Finished",
  "status": "Ok",
  "message": "Task completed successfully",
  "userid": "admin",
  "created_on": "2015-05-05T19:37:32Z",
  "updated_on": "2015-05-05T19:37:38Z"
}

3.8.3. Setting the Virtual Machine Owner

3.8.3.1. Request:

POST /api/vms/1921
{
  "action": "set_owner",
  "resource" : {
    "owner" : "admin"
  }
}

3.8.3.2. Response:

{
  "success": true,
  "message": "VM id:1921 name:'aab_demo_vm' setting owner to 'admin'",
  "href": "https://hostname/api/vms/1921"
}

3.8.4. Adding an Event to a Virtual Machine

3.8.4.1. Request:

POST /api/vms/1921
{
  "action": "add_event",
  "resource" : {
    "event_type" : "BadUserNameSessionEvent",
    "event_message" : "Cannot login user@test.domain"
  }
}

3.8.4.2. Response:

{
  "success": true,
  "message": "Adding Event type=BadUserNameSessionEvent message=Cannot login user@test.domain",
  "href": "https://hostname/api/vms/1921"
}

3.8.5. Adding a Lifecycle Event to a Virtual Machine

3.8.5.1. Request:

POST /api/vms/1921
{
  "action" : "add_lifecycle_event",
  "resource" : {
    "event" : "event_name",
    "status" : "event_status",
    "message" : "Message about the event",
    "created_by" : "user_name"
  }
}

3.8.5.2. Response:

{
  "success": true,
  "message": "VM id:1921 name:'aab_demo_vm' adding lifecycle event=event_name message=Message about the event",
  "href": "https://hostname/api/vms/1921"
}

3.8.6. Starting a Virtual Machine

3.8.6.1. Request:

POST /api/vms/1921
{
  "action": "start"
}

3.8.6.2. Response:

{
  "success": true,
  "message": "VM id:1921 name:'aab_demo_vm' starting",
  "task_id": 610,
  "task_href": "https://hostname/api/tasks/610",
  "href": "https://hostname/api/vms/1921"
}

3.8.7. Querying Task Progress

3.8.7.1. Request:

GET /api/tasks/620

3.8.7.2. Response:

{
  "href": "https://hostname/api/tasks/610",
  "id": 610,
  "name": "VM id:1921 name:'aab_demo_vm' starting",
  "state": "Queued",
  "status": "Ok",
  "message": "Queued the action: [VM id:1921 name:'aab_demo_vm' starting] being run for user: [admin]",
  "userid": "admin",
  "created_on": "2015-05-05T15:58:08Z",
  "updated_on": "2015-05-05T15:58:08Z"
}

3.8.8. Stopping a Virtual Machine

3.8.8.1. Request:

POST /api/vms/1921
{
  "action": "stop"
}

3.8.8.2. Response:

{
  "success": true,
  "message": "VM id:1921 name:'aab_demo_vm' stopping",
  "task_id": 619,
  "task_href": "https://hostname/api/tasks/619",
  "href": "https://hostname/api/vms/1921"
}

3.8.9. Suspending a Virtual Machine

3.8.9.1. Request:

POST /api/vms/1921
{
  "action": "suspend"
}

3.8.9.2. Response:

{
  "success": true,
  "message": "VM id:1921 name:'aab_demo_vm' suspending",
  "task_id": 620,
  "task_href": "https://hostname/api/tasks/620",
  "href": "https://hostname/api/vms/1921"
}

3.8.10. Deleting Virtual Machines

3.8.10.1. Deleting a Single Virtual Machine

3.8.11. Request:

DELETE /api/vms/334

On success, the virtual machine targeted for deletion asynchronously and no response content with an HTTP status code of 204 are returned.

3.8.11.1. Deleting Multiple Virtual Machines

3.8.12. Request:

DELETE /api/vms
{
  "action" : "delete",
  "resources" : [
    { "href" : "https://hostname/api/vms/348" },
    { "href" : "https://hostname/api/vms/349" },
    { "href" : "https://hostname/api/vms/3" }
  ]
}

3.8.13. Response:

{
  "results": [
    {
      "success": true,
      "message": "VM id:348 name:'aab-temp1' deleting",
      "task_id": 616,
      "task_href": "https://hostname/api/tasks/616",
      "href": "https://hostname/api/vms/348"
    },
    {
      "success": true,
      "message": "VM id:349 name:'aab-temp2' deleting",
      "task_id": 617,
      "task_href": "https://hostname/api/tasks/617",
      "href": "https://hostname/api/vms/349"
    }
  ]
}

Optionally, monitor the asynchronous virtual machine deletion by accessing the related task as follows:

3.8.14. Request:

GET /api/tasks/616

3.8.15. Response:

{
  "href": "https://hostname/api/tasks/616",
  "id": 616,
  "name": "VM id:348 name:'aab-temp1' deleting",
  "state": "Finished",
  "status": "Ok",
  "message": "Task completed successfully",
  "userid": "admin",
  "created_on": "2015-05-05T19:33:35Z",
  "updated_on": "2015-05-05T19:33:40Z"
}

3.9. Service Templates

This section provides examples of how to interact with service templates.

3.9.1. Editing a Service Template

3.9.1.1. Request:

POST /api/service_templates/2
{
  "action" : "edit",
  "resource" : {
    "name" : "updated_svc_template_02",
    "description" : "This is an updated description for service template 02"
  }
}

3.9.1.2. Response:

{
  "href": "https://hostname/api/service_templates/2",
  "id": 2,
  "name": "updated_svc_template_02",
  "description": "This is an updated description for service template 02",
  "guid": "6f7918b4-d6e7-11e4-9837-b8e85646e742",
  "options": {
  },
  "created_at": "2015-03-30T14:17:02Z",
  "updated_at": "2015-04-16T22:30:02Z",
  "service_type": "unknown",
  "service_template_catalog_id": 6
}

3.9.2. Editing Multiple Service Templates

3.9.2.1. Request:

POST /api/service_templates
{
  "action" : "edit",
  "resources" : [
    {
      "href" : "https://hostname/api/service_templates/1",
      "description" : "This is an updated description for the first sample service template"
    },
    {
      "href" : "https://hostname/api/service_templates/2",
      "description" : "This is an updated description for the second sample service template"
    }
  ]
}

3.9.2.2. Response:

{
  "results": [
    {
      "id": 1,
      "name": "template1",
      "description": "This is an updated description for the first sample service template",
      "guid": "6a6fdf7e-d6e7-11e4-9837-b8e85646e742",
      "options": {
      },
      "created_at": "2015-03-30T14:16:53Z",
      "updated_at": "2015-04-16T22:33:09Z",
      "service_type": "unknown",
      "service_template_catalog_id": 3
    },
    {
      "id": 2,
      "name": "updated_svc_template_02",
      "description": "This is an updated description for the second sample service template",
      "guid": "6f7918b4-d6e7-11e4-9837-b8e85646e742",
      "options": {
      },
      "created_at": "2015-03-30T14:17:02Z",
      "updated_at": "2015-04-16T22:33:09Z",
      "service_type": "unknown",
      "service_template_catalog_id": 6
    }
  ]
}

3.9.3. Deleting Multiple Service Templates

3.9.3.1. Request:

POST /api/service_templates
{
  "action" : "delete",
  "resources" : [
    { "href" : "https://hostname/api/service_templates/4" },
    { "href" : "https://hostname/api/service_templates/5" }
  ]
}

3.9.3.2. Response:

{
  "results": [
    {
      "success": true,
      "message": "service_templates id: 4 deleting",
      "href": "https://hostname/api/service_templates/4"
    },
    {
      "success": true,
      "message": "service_templates id: 5 deleting",
      "href": "https://hostname/api/service_templates/5"
    }
  ]
}

3.10. Containers

This section provides examples of how to interact with containers.

3.10.1. Scanning Containers

Scan containers using SmartState Analysis.

Note
  • Scanning containers requires enabling the SmartProxy server role. See Servers in the General Configuration Guide for information on server roles.
  • Attached OpenSCAP policies do not affect responses.

3.10.1.1. Request:

POST /api/container_images/440
{
  "action": "scan"
}

3.10.1.2. Response:

{
"success": true,
"message": "ContainerImage id:440 name:'cbud_test_cont' scanning",
"task_id": "2133",
"task_href": "https://<hostname>/api/tasks/2133",
"href": "https://<hostname>/api/container_images/440"
}

3.11. Datastores

This section provides examples of how to interact with datastores.

3.11.1. Deleting Datastores

3.11.1.1. Request:

POST /api/data_stores
{
  "action" : "delete",
  "resources" : [
    { "href" : "https://hostname/api/data_stores/7" },
  ]
}

3.11.1.2. Response:

{
    "results": [
        {
            "success": true,
            "message": "Deleting Data Store id:7 name:'NFS_Datastore_1'",
            "task_id": "1",
            "task_href": "https://hostname/api/tasks/1",
            "href": "https://hostname/api/data_stores/7"
        }
    ]
}

Confirm the task deleted successfully using the task_id in the response.

3.11.1.3. Request:

GET /api/tasks/1

3.11.1.4. Response:

{
    "href": "https://hostname/api/tasks/1",
    "id": "1",
    "name": "Deleting Data Store id:7 name:'NFS_Datastore_1'",
    "state": "Finished",
    "status": "Ok",
    "message": "Task completed successfully",
    "userid": "admin",
    "created_on": "2018-08-22T08:35:26Z",
    "updated_on": "2018-08-22T08:35:34Z",
    "pct_complete": null,
    "context_data": null,
    "results": null,
    "miq_server_id": "1",
    "identifier": null,
    "started_on": "2018-08-22T08:35:34Z",
    "zone": null,
    "actions": [
        {
            "name": "delete",
            "method": "post",
            "href": "https://hostname/api/tasks/1"
        },
        {
            "name": "delete",
            "method": "delete",
            "href": "https://hostname/api/tasks/1"
        }
    ]
}
------