Chapter 2. Reference Guide

2.1. Authentication

TypeMechanism

Basic Authentication

Basic HTTP Authorization with user and password

Token Based Authentication

 

- Acquiring Token

/api/auth with Basic Authentication

- Authenticating with Token

X-Auth-Token Header

2.2. HTTP Headers

HeaderValue

Authorization

Basic base64_encoded(user:password)

X-Auth-Token

Token provided by /api/auth

Accept

application/json

Content-Type

application/json

2.3. Listing and Querying Collections and Sub-Collections

FeaturePath

Listing Available Collections

/api

Listing Collections

/api/<collection>

Listing Sub-Collections

/api/<collection>/<id>/<sub-collection>

Querying CapabilityQuery Parameters

Paging

offset, limit

Sorting

sort_by=attr, sort_order=asc|desc

Filtering

filter[]="…​"

Querying by Tag

i.e. by_tag=/department/finance

Expanding Results

expand=<what>, i.e. expand=resources,tags,service_templates,…​

Selecting Attributes

attributes=<attr1>,<attr2>,…​ i.e. attributes=id,name,type,…​

 

Attributes can be:

 

Database columns

 

Virtual attributes

 

Relationships

2.4. Collection Queries

CollectionURL

Automation Requests

/api/automation_requests

Availability Zones

/api/availability_zones

Cloud Networks

/api/cloud_networks

Cloud Subnets

/api/cloud_subnets

Clusters

/api/clusters

Conditions

/api/conditions

Container Images

/api/container_images/

Datastores

/api/data_stores

Events

/api/events

Flavors

/api/flavors

Groups

/api/groups

Hosts

/api/hosts

Network Routers

/api/network_routers

Policies

/api/policies

Actions

/api/policy_actions

Policy Profiles

/api/policy_profiles

Providers

/api/providers

Provision Requests

/api/provision_requests

Request Tasks

/api/request_tasks

Requests

/api/requests

Resource Pools

/api/resource_pools

Roles

/api/roles

Security Groups

/api/security_groups

EVM Servers

/api/servers

Service Catalogs

/api/service_catalogs

Service Requests

/api/service_requests

Service Templates

/api/service_templates

Services

/api/services

Tags

/api/tags

Tasks

/api/tasks

Templates

/api/templates

Users

/api/users

Vms

/api/vms

Zones

/api/zones

For example queries, see "Queries".

2.5. Sub-Collection Queries

Sub-CollectionURL

Tagging

/api/<collection>/:id/tags

Policies

/api/<collection>/:id/policies

Policy Profiles

/api/<collection>/:id/policy_profiles

  

Service Requests

/api/service_templates/:id/service_requests

Request Tasks

 
 

/api/service_requests/:id/request_tasks

 

/api/automation_requests/:id/request_tasks

 

/api/provision_requests/:id/request_tasks

Request Tasks can also be accessed via the tasks alias

 
 

/api/service_requests/:id/tasks

 

/api/automation_requests/:id/tasks

 

/api/provision_requests/:id/tasks

Infrastructure Providers

 
 

/api/providers/:id/lans

 

/api/hosts/:id/lans

 

/api/providers/:id/networks

 

/api/providers/:id/folders (also returns Datacenters)

2.6. Available Actions

ActionMethodURL

Add Service Catalog

POST

/api/service_catalogs

Add Service Catalogs

POST

/api/service_catalogs

Edit Service Catalog

POST

/api/service_catalogs/id

Edit Service Catalogs

POST

/api/service_catalogs

Automation Request

POST

/api/automation_requests

Automation Requests

POST

/api/automation_requests

Edit Service

POST

/api/services/id

Edit Service via PUT

PUT

/api/services/id

Edit Service via PATCH

PATCH

/api/services/id

Edit Services

POST

/api/services/

Assign Tags to a Service

POST

/api/services/id/tags

Assign a Tag by Name to a Service

POST

/api/services/id/tags

Assign a Tag by Name to a Service

POST

/api/services/id/tags

Unassign Tags from Service

POST

/api/services/id/tags

Assign Tags to Cloud Networks

POST

/api/cloud_networks/id/tags

Assign Tags to Cloud Subnets

POST

/api/cloud_subnets/id/tags

Assign Tags to Flavors

POST

/api/flavors/id/tags

Assign Tags to Availability Zones

POST

/api/availability_zones/id/tags

Assign Tags to Network Routers

POST

/api/network_routers/id/tags

Assign Tags to Security Groups

POST

/api/security_groups/id/tags

Retire Service Now

POST

/api/services/id

Retire Service in Future

POST

/api/services/id

Retire Services

POST

/api/services

Delete Service

DELETE

/api/services/id

Delete Services

POST

/api/services

Edit Service Template

POST

/api/service_templates/id

Edit Service Templates

POST

/api/service_templates

Assign Tags to Service Template

POST

/api/service_templates/id/tags

Unassign Tags from Service Template

POST

/api/service_templates/id/tags

Delete Service Template

DELETE

/api/service_templates/id

Delete Service Templates

POST

/api/service_templates

Assign Service Templates

POST

/api/service_catalogs/id/service_templates

Unassign Service Templates

POST

/api/service_catalogs/id/service_templates

Order Service

POST

/api/service_catalogs/id/service_templates

Order Services

POST

/api/service_catalogs/id/service_templates

Delete Service Catalog

DELETE

/api/service_catalogs/id

Delete Service Catalogs

POST

/api/service_catalogs

Provision Request

POST

/api/provision_requests

Provision Requests

POST

/api/provision_requests

Create a Provider

POST

/api/providers

Create a Provider with Compound Credentials

POST

/api/providers

Edit a Provider

POST

/api/providers

Update a Provider

POST

/api/providers

Delete a Provider

POST

/api/providers

Delete Multiple Providers

POST

/api/providers

Refresh a Provider

POST

/api/providers

Scan a VM

POST

/api/vms

Set Owner of a VM

POST

/api/vms

Add a Lifecycle Event to a VM

POST

/api/vms

Add an Event to a VM

POST

/api/vms

Start a VM

POST

/api/vms

Stop a VM

POST

/api/vms

Suspend a VM

POST

/api/vms

Delete VMs

DELETE

/api/vms

Scan a Container

POST

/api/container_images

2.7. Provisioning Request Attributes

2.7.1. Provisioning Request Attribute Groups

Attribute GroupTypeDescription

version

string

Interface version. Defaults to 1.1

template_fields

hash

Fields used to find the template virtual machine. Provide any or all fields. Supply a guid or ems_guid to protect against matching same-named templates on different Providers within the appliance.

Supported fields are: name=[VM Template Name] Example: template_1 guid=[guid value from vms resource] ems_guid=[uid_ems value from vms resource]

vm_fields

hash

Allows for setting properties on the Service Catalog, Hardware, Network, Customize, and Schedule tabs in the Provisioning dialog.

requester

hash

Allows for the setting of properties on the Requester tab in the Provisioning dialog.

tags

hash

Tags to apply to newly created virtual machine.

Example: network_location=Internal cc=001

additional_values

hash

Additional values are name-value pairs stored with a provision request, but not used by the core provisioning code. These values are usually referenced from automate methods for custom processing.

Example: Store a request_id from an external system so the system can be notified during the provisioning process.

ems_custom_attributes

hash

Custom attributes applied to the virtual machine through the Provider as part of provisioning.

miq_custom_attributes

hash

Custom attributes applied to the virtual machine and stored in the database as part of provisioning.

2.7.2. Service Catalog Attributes

These attributes are used in the vm_fields attribute group:

AttributeTypeDescriptionDefault

number_of_vms

integer

Number of virtual machines - maximum 50

1

vm_description

string

Virtual machine description - maximum 100 characters

 

vm_prefix

string

Virtual machine name prefix or suffix

 

src_vm_id

integer

Name

 

vm_name

string

Virtual machine name

 

pxe_image_id

string

Image

 

pxe_server_id

integer

Server

 

host_name

string

Host name

 

provision_type

string

Provision type

vmware

linked_clone

boolean

Linked clone

false

snapshot

string

Snapshot

 

vm_filter

integer

Filter

 

2.7.3. Hardware Attributes

These attributes are used in the vm_fields attribute group:

AttributeTypeDescriptionValuesDefault

disk_format

string

Disk format

thick, thin, unchanged

unchanged

cpu_limit

integer

CPU (MHz)

  

memory_limit

integer

Memory (MB)

  

number_of_sockets

integer

Number of sockets

1, 2, 4, 8

1

cores_per_socket

integer

Cores per socket

1, 2, 4, 8

1

cpu_reserve

integer

CPU (MHz)

  

vm_memory

string

Memory (MB)

1024, 2048, 4096

1024

memory_reserve

integer

Memory (MB)

  

network_adapters

integer

Network adapters

1, 2, 3, 4

1

2.7.4. Network Attributes

These attributes are used in the vm_fields attribute group:

AttributeTypeDescription

vlan

string

vLAN

mac_address

string

MAC address

2.7.5. Custom Attributes

These attributes are used in the vm_fields attribute group:

AttributeTypeDescriptionValuesDefault

dns_servers

string

DNS server list

  

sysprep_organization

string

Organization

  

sysprep_password

string

New administrator password

  

sysprep_custom_spec

string

Name (Note: This is not supported when being passed by VMware through an API call.)

  

sysprep_server_license_mode

string

Identification

perServer, perSeat

 

ldap_ous

string

LDAP group

  

sysprep_timezone

string

Timezone

  

dns_suffixes

string

DNS suffix list

  

sysprep_product_id

string

ProductID

  

sysprep_identification

string

Identification

domain, workgroup

 

sysprep_per_server_max_connections

string

Maximum connections

 

5

sysprep_computer_name

string

Computer name

  

sysprep_workgroup_name

string

Workgroup name

 

WORKGROUP

sysprep_spec_override

boolean

Override specification

 

false

addr_mode

string

Address mode

static, dhcp

dhcp

linux_host_name

string

Computer name

  

sysprep_domain_admin

string

Domain admin

  

sysprep_change_sid

boolean

Change SID

 

true

sysprep_domain_name

string

Domain name

  

sysprep_upload_file

string

Upload

  

gateway

string

Gateway

  

ip_addr

string

IP address

  

linux_domain_name

string

Domain name

  

sysprep_domain_password

string

Domain password

  

sysprep_auto_logon

boolean

Auto Logon

 

true

sysprep_enabled

string

Customize

 

disabled

sysprep_delete_accounts

boolean

Delete accounts

 

false

sysprep_upload_text

string

Sysprep text

  

wins_servers

string

WINS server list

  

subnet_mask

string

Subnet mask

  

sysprep_full_name

string

Full name

  

sysprep_auto_logon_count

integer

Auto logon count

1, 2, 3

1

customization_template_id

integer

Script name

  

root_password

string

Root password

  

hostname

string

Host name

  

customization_template_script

string

Script text

  

2.7.6. Schedule Attributes

These attributes are used in the vm_fields attribute group:

AttributeTypeDescriptionValuesDefault

schedule_type

string

When to provision

schedule, immediately (On Approval)

immediately

vm_auto_start

boolean

Power on virtual machines after creation

 

true

schedule_time

time

Time to provision on

  

retirement

integer

Time until retirement

0 (Indefinite), 1.month, 3.months, 6.months

0

retirement_warn

integer

Retirement warning

1.week, 2.weeks, 30.days

1.week

2.7.7. Requester Attributes

These attributes are used in the requester attribute group:

AttributeTypeDescription

owner_phone

string

Phone

owner_country

string

Country/Region

owner_phone_mobile

string

Mobile phone

owner_title

string

Title

owner_first_name

string

First name

owner_manager

string

Manager name

owner_address

string

Address

owner_company

string

Company

owner_last_name

string

Last name

owner_manager_email

string

Manager e-mail address

owner_city

string

City

owner_department

string

Department

owner_load_ldap

button

Look up LDAP e-mail address

owner_manager_phone

string

Manager phone

owner_state

string

State

owner_office

string

Office

owner_zip

string

Zip code

owner_email

string

E-Mail

request_notes

string

Notes

2.7.8. Environment Attributes

These attributes cannot be passed directly. To use these attributes, provide additional_values and allow customization methods to use these attributes, then modify the request accordingly.

AttributeTypeDescriptionValuesDefault

new_datastore_grow_increment

integer

Grow increment (GB)

  

new_datastore_create

boolean

Create datastore

 

false

placement_cluster_name

integer

Name

  

new_datastore_aggregate

string

Aggregate

  

new_datastore_max_size

integer

Max size (GB)

  

new_datastore_storage_controller

string

Controller

  

cluster_filter

integer

Filter

  

host_filter

integer

Filter

  

ds_filter

integer

Filter

  

new_datastore_volume

string

Volume

  

placement_host_name

integer

Name

  

placement_ds_name

integer

Name

  

new_datastore_fs_type

string

FS Type

NFS, VMFS

NFS

rp_filter

integer

Filter

  

new_datastore_thin_provision

string

Thin provision

  

placement_auto

boolean

Choose automatically

 

false (NOTE: placement_auto defaults to true for requests made from the API or CloudForms Automate.)

new_datastore_size

integer

Size (GB)

  

new_datastore_autogrow

string

Autogrow

 

false

placement_folder_name

integer

Name

  

new_datastore_name

string

Name

  

placement_rp_name

integer

Name

  

placement_dc_name

integer

Name