Service management is provided via the following collections:
| Path | Description |
|---|---|
| /api/service_catalogs | Service Catalogs |
| /api/service_templates | Service Templates |
| /api/services | Services |
| /api/service_requests | Service Requests |
Full CRUD is available on service catalogs.
/api/service_catalogs
Creating service catalog is provided via the following actions:
| Method | Versions | Comment |
|---|---|---|
| create | 2.0.0 | Preferred |
| add | since v1.0 |
Example of creating service catalog with create method:
POST /api/service_catalogs
{
"action" : "create",
"resource" : {
"name" : "Sample Service Catalog",
"description" : "Description of Sample Service Catalog",
"service_templates" : [
{ "href" : "http://localhost:3000/api/service_templates/3" },
{ "href" : "http://localhost:3000/api/service_templates/4" }
]
}
}
Optionally without the create action signature:
{
"name" : "Sample Service Catalog",
"description" : "Description of Sample Service Catalog",
"service_templates" : [
{ "href" : "http://localhost:3000/api/service_templates/3" },
{ "href" : "http://localhost:3000/api/service_templates/4" }
]
}
Note:
Please refer to the Resource Attributes page for a list of available attributes when creating Service Catalogs.
Editing a service catalog via the edit action as follows:
POST /api/service_catalogs/:id
{
"action" : "edit",
"resource" : {
"description" : "Updated Description of Third Service Catalog"
}
}
Assign and Unassigning service templates to service catalogs is done via the assign and unassign actions as follows:
POST /api/service_catalogs/:id
{
"action" : "assign",
"resources" : [
{ "href" : "http://localhost:3000/api/service_templates/5" },
{ "href" : "http://localhost:3000/api/service_templates/6" }
]
}
POST /api/service_catalogs/:id
{
"action" : "unassign",
"resources" : [
{ "href" : "http://localhost:3000/api/service_templates/1" },
{ "href" : "http://localhost:3000/api/service_templates/2" }
]
}
Ordering services is done by triggering an order action on service templates in a service catalog as follows:
POST /api/service_catalogs/:id/service_templates
{
"action" : "order",
"resource" : {
"href" : "http://localhost:3000/api/service_templates/3",
"option_0_vm_target_name" : "test-vm-0001",
"option_0_vm_target_hostname" : "test-vm-0001"
}
}
Refreshing dialog fields is done via a refresh_dialog_fields action as shown in the following cases:
Refreshing dialog fields for a service template service dialogs is done as follows:
POST /api/service_catalogs/:id/service_templates
{
"action" : "refresh_dialog_fields",
"resource" : {
"href" : "http://localhost:3000/api/service_templates/3",
"dialog_fields" : {
"my_field1" : "my field1 value",
"my_field2" : "my field2 value",
"my_field3" : "my field3 value",
...
},
"fields" : [ "my_field1", "my_field3" ]
}
}
Refreshing dialog fields for a service dialog is done as follows:
POST /api/service_dialogs/:id
{
"action" : "refresh_dialog_fields",
"resource" : {
"dialog_fields" : {
"my_field1" : "my field1 value",
"my_field2" : "my field2 value",
"my_field3" : "my field3 value",
...
},
"fields" : [ "my_field1", "my_field3" ]
}
}
Single service catalogs can simply be deleted via the DELETE method as follows:
DELETE /api/service_catalogs/:id
Multiple service catalogs can also be deleted with a single request as follows:
POST /api/service_catalogs
{
"action" : "delete",
"resources" : [
{ "href" : "http://localhost:3000/api/service_catalogs/11" },
{ "href" : "http://localhost:3000/api/service_catalogs/12" },
{ "href" : "http://localhost:3000/api/service_catalogs/13" }
]
}
Management of Service Templates is available via the following collection:
/api/service_templates
Full CRUD is available on service templates.
Service Templates can be created via a POST to the /api/service_templates collection:
/api/service_templates
{
"name" : "Atomic Service Template",
"service_type" : "atomic",
"prov_type" : "amazon",
"display" : "false",
"config_info" : {
"miq_request_dialog_name" : "Dialog_Name",
"placement_auto" : [true, 1],
"number_of_vms" : [1, "1"],
"src_vm_id" : [11, "test_vm"],
"vm_name" : "AtomicVMName",
"schedule_type" : ["immediately", "Immediately on Approval"],
"instance_type" : [21, "instance_flavor"],
"src_ems_id" : [5, "test_provider"],
"provision" : {
"fqname" : "/Sample/System/ProvisionEndpoint",
"dialog_id" : "21"
},
"retirement" : {
"fqname" : "/Sample/System/RetirementEndpoint",
"dialog_id" : "22"
}
}
}
Editing a single service template as follows:
POST /api/service_templates/:id
{
"action" : "edit",
"resource" : {
"name" : "svc_template_01",
"description" : "This is a sample service template"
}
}
Deleting single service template via the DELETE method:
DELETE /api/service_templates/:id
or via the delete action as follows:
POST /api/service_templates/:id
{
"action" : "delete"
}
Multiple service templates can also be deleted in bulk as follows:
POST /api/service_templates
{
"action" : "delete",
"resources" : [
{ "href" : "http://localhost:3000/api/service_templates/11" },
{ "href" : "http://localhost:3000/api/service_templates/12" }
]
}
Accessing services is via the services collection as follows:
/api/services
or addressing an individual Service via the services resource:
/api/services/:id
In general, services are created once ordered from service catalogs.
Service resources can also be created as follows:
POST /api/services
{
"action" : "create",
"resource" : {
"name" : "test_service_name",
"description" : "Test Service",
"parent_service" : { "href" : "http://localhost:3000/api/services/15" }
}
}
In the above example parent_service is an href or id reference to an existing service.
Note:
Please refer to the Resource Attributes page for a list of available attributes when creating Services.
Once services are ordered from a catalog, they can be:
Additional Service actions include:
Other than service creates and edits, service actions return the action response as in the following example:
Request:
POST /api/services/12
{
"action" : "start"
}
Response:
{
"success": true,
"message": "Service id:12 name:'SampleService' starting",
"task_id": "62",
"task_href": "http://localhost:3000/api/tasks/62",
"href": "http://localhost:3000/api/services/12"
}
POST /api/services/:id
{
"action" : "edit",
"resource" : {
"name" : "Updated Service Name",
"description" : "Updated Service Description"
}
}
Adding and removing resources from services is made available with the following actions:
| Action |
|---|
| add_resource |
| remove_resource |
| remove_all_resources |
The following example adds a single resource to a service:
POST /api/services/:id
{
"action" : "add_resource",
"resource" : { "resource" : { "href" : "http://localhost:3000/api/vms/11" } }
}
The following example bulk adds resources to multiple services:
POST /api/services
{
"action" : "add_resource",
"resources" : [
{
"href" : "http://localhost:3000/api/services/3",
"resource" : { "href" : "http://localhost:3000/api/vms/11" }
},
{
"href" : "http://localhost:3000/api/services/3",
"resource" : { "href" : "http://localhot:3000/api/vms/12" }
},
{
"href" : "http://localhost:3000/api/services/4",
"resource" : { "href" : "http://localhost:3000/api/vms/21" }
},
{
"href" : "http://localhost:3000/api/services/5",
"resource" : { "href" : "http://localhost:3000/api/vms/22" }
}
]
}
The following example removes a single resource from a service:
POST /api/services/:id
{
"action" : "remove_resource",
"resource" : { "resource" : { "href" : "http://localhost:3000/api/vms/11" } }
}
The following example removes resources in bulk from multiple services:
POST /api/services
{
"action" : "remove_resource",
"resources" : [
{
"href" : "http://localhost:3000/api/services/3",
"resource" : { "href" : "http://localhost:3000/api/vms/11" }
},
{
"href" : "http://localhost:3000/api/services/3",
"resource" : { "href" : "http://localhot:3000/api/vms/12" }
},
{
"href" : "http://localhost:3000/api/services/4",
"resource" : { "href" : "http://localhost:3000/api/vms/21" }
},
{
"href" : "http://localhost:3000/api/services/5",
"resource" : { "href" : "http://localhost:3000/api/vms/22" }
}
]
}
The following example removes all resources from a single service:
POST /api/services/:id
{
"action" : "remove_all_resources"
}
The following example removes all resources in bulk from multiple services:
POST /api/services
{
"action" : "remove_all_resources",
"resources" : [
{ "href" : "http://localhost:3000/api/services/11" },
{ "href" : "http://localhost:3000/api/services/12" },
{ "href" : "http://localhost:3000/api/services/13" }
]
}
For cases where VMs are created externally, i.e. via Ansible Playbooks, this action allows the system to identify the VMs created and link those VMs back to the service.
POST /api/services/:id
{
"action" : "add_provider_vms",
"resource" : {
"provider" : { "href" : "http://localhot:3000/api/providers/11" }
"uid_ems" : [
"provider_vm_id1",
"provider_vm_id2",
...
]
}
}
This action will request a chargeback report for the service.
POST /api/services/:id
{
"action" : "queue_chargeback_report"
}
The queue_chargeback_report action will return an action response which includes the task reference as shown here:
{
"success": true,
"message": "Queued chargeback report generation for Service id:1 name:'test_service1'",
"task_id": "39",
"task_href": "http://localhost:3000/api/tasks/39"
}
The task_href can be queried and upon completion of the task, the chargeback report for the service can be queried as follows:
GET /api/services/:id?attributes=chargeback_report
POST /api/services/:id
{
"action" : "request_retire"
}
POST /api/services/:id
{
"action" : "request_retire",
"resource" : { "date" : "10/30/2015", "warn" : "5" }
}
When a service is defined with a Reconfigure Automation Entrypoint, the reconfigure action is shown as a valid action for that service.
This action takes any of the dialog fields the service supports during reconfiguration.
POST /api/services/:id
{
"action" : "reconfigure",
"resource" : {
"field1" : "updated field1 value",
"field2" : "updated field2 value",
...
}
}
POST /api/services/:id
{
"action" : "start"
}
POST /api/services/:id
{
"action" : "stop"
}
POST /api/services/:id
{
"action" : "suspend"
}
DELETE /api/services/:id
Or via the delete action for deleting multiple services:
POST /api/services
{
"action" : "delete",
"resources" : [
{ "href" : "http://localhost:3000/api/services/101",
{ "href" : "http://localhost:3000/api/services/102",
{ "href" : "http://localhost:3000/api/services/103"
...
]
}
Once services are ordered from a catalog, service requests can be monitored as follows:
GET /api/service_requests/:id
Note:
The request tasks of service requests can be queried by expanding the request_tasks as follows:
GET /api/service_requests/:id?expand=request_tasks
or by fetching them directly as follows:
GET /api/service_requests/:id/request_tasks?expand=resources
If a service request is not auto approved, it can be approved or denied via the actions approve and deny on the service request resource.
POST /api/service_requests/:id
{
"action" : "approve",
"reason" : "reason for approval"
}
POST /api/service_requests/:id
{
"action" : "deny",
"reason" : "reason for denial"
}
Approvers can be added to service requests with the add_approver action. Approvers can be specified by user_id or user reference including an href or id of the approver.
POST /api/service_requests/:id
{
"action" : "add_approver",
"resource" : {
"user_id" : 11
}
}
Or one of the following signatures:
{
"action" : "add_approver",
"resource" : {
"user" : { "id" : 11 }
}
}
{
"action" : "add_approver",
"resource" : {
"user" : { "href" : "http://localhost:3000/api/users/11" }
}
}
Approvers can also be added in bulk as follows:
POST /api/service_requests
{
"action" : "add_approver",
"resources" : [
{
"href" : "http://localhost:3000/api/service_requests/101",
"user_id" : "11"
},
{
"href" : "http://localhost:3000/api/service_requests/102",
"user" : { "id" : 11 }
},
{
"href" : "http://localhost:3000/api/service_requests/103",
"user" : { "href" : "http://localhost:3000/api/users/11" }
}
]
}
Approvers can be removed from service requests with the remove_approver action. Approvers can be specified by user_id or user reference including an href or id of the approver.
POST /api/service_requests/:id
{
"action" : "remove_approver",
"resource" : {
"user_id" : "11"
}
}
Approvers can also be removed in bulk as follows:
POST /api/service_requests
{
"action" : "remove_approver",
"resources" : [
{
"href" : "http://localhost:3000/api/service_requests/101",
"user_id" : "11"
},
{
"href" : "http://localhost:3000/api/service_requests/102",
"user" : { "id" : "11" }
},
{
"href" : "http://localhost:3000/api/service_requests/103",
"user" : { "href" : "http://localhost:3000/api/users/11" }
}
]
}
Request tasks of Service Requests can be updated as follows:
POST /api/service_requests/:id/request_tasks/:request_task_id
{
"action" : "edit",
"resource" : {
"options" : {
"request_param_a" : "value_a",
"request_param_b" : "value_b"
}
}
}