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

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.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" : "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" : "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" : "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" : "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"
    }
  ]
}