This is an overview of the new RESTful API in the ManageIQ Anand release. Build cross-cloud applications and management systems using ManageIQ as a developer platform. More more on ManageIQ, see http://manageiq.org/

1. ‹#›
ManageIQ RestAPI
John Hardy
John Hardy
Product Manager
Fall 2014

2. Agenda
• What is RestAPI
• Why have RestAPI
• Use Cases
• How to Play
• Authentication
• Technical Syntax
‹#›
• Get
• Post
• Put
• Automation Request
• Provisioning Request
• Further Information
• Q&A

3. What is RestAPI?
REST stands for Representational State Transfer. It relies
‹#›
on a stateless, client-server, cacheable communications
protocol -- and in virtually all cases, the HTTP protocol
is used.
REST is an architecture style for designing networked
applications. The idea is that, rather than using complex
mechanisms such as CORBA, RPC or SOAP to connect
between machines, simple HTTP is used to make calls
between machines.

4. Why have RestAPI?
RESTs sweet spot is when you are exposing a public API over the
‹#›
internet to handle CRUD operations on data. REST is focused
on accessing named resources through a single consistent
interface.
REST permits many different data formats where as SOAP only
permits XML. While this may seem like it adds complexity to
REST because you need to handle multiple formats, in my
experience it has actually been quite beneficial. JSON usually is
a better fit for data and parses much faster. REST allows better
support for browser clients due to it’s support for JSON.
REST has better performance and scalability. REST reads can be
cached, SOAP based reads cannot be cached.

5. Use Cases - 1
Northbound and Southbound interfacing.
We are automated
ITSM products connect to ManageIQ to gather data or initiate
‹#›
tasks in ManageIQ.
Example – Service Catalogue reads from ManageIQ the list of
VM Templates in the system for presentation in a list box.
Example – Help Desk software initiates a smart state analysis
upon a software ticket to help better diagnose the issue.
Example – Business Process Management initiates a VM
deployment, by calling into ManageIQ to provision using criteria
it has chosen or allowing ManageIQ to intelligently make the
decisions itself.

6. Use Cases – 2
Northbound and Southbound interfacing.
We automate
ManageIQ calls out to external services for automation and
‹#›
information.
Example – We request information from an external system to
enhance the provisioning placement of virtual machines.
Example – We call automation in other systems to do things for
us, like create a virtual distributed switch via vCO in vSphere.
Example – We create a ticket in an ITSM product adding
enhanced reporting detail to the ticket.

7. How to play
Various RestAPI tools are available, as its HTTP based anything thing can be
‹#›
used, here are a few;
Internet Browser – Usually the first thing to try with RestAPI is to put a RestAPI
call into your browser URL field and see what happens. (It works!)
CURL – Command Line HTTP client, Example;
curl --user admin:smartvm -i -X GET -H "Accept: application/json"
http://localhost:3000/api/services
SOAPUI – A great utility available on Mac OS X, Linux and Windows. Allows you
to graphically interact with Rest and Soap services.
CFME Rest API Client – The developer behind the RestAPI for CFME has kindly
added a command line Rest Client to make things quicker/easier. More
information on this later in this deck.

8. CFME RestAPI Client - 1
The CFME RestAPI Client can be found in;
/var/www/miq/lib/cfme_client
You can either run the /bin/rest_api.rb or link to the file as I have done for these
demos;
ln –s <path to file>rest_api.rb <path to file>api
To test
./api -- version
returns
api 1.0 - CFME REST API Access Script
I had to install some GEMs in addition to the standard ones I had on MAC OS X.
• faraday_middleware
• faraday
‹#›

9. CFME RestAPI Client - 2
api 1.0 - CFME REST API Access Script
Usage: api [options] <action> [parameters] [resource]
‹#›
action - is the action to use for the request, i.e. get, post, patch, edit ...
[parameters] include: expand, attributes, limit, offset, sort_by, sort_order, sqlfilter, by_tag
specify --help for additional help
[resource] - is the optional resource i.e. services
api [options] vi|edit [script]
Edit optional api_* scripts. script names must be specified without the
api_ prefix or .rb suffix. Edits this script if not specified.
api [options] run script [method]
Run optional api_* scripts
api [options] ls
List optional api_* scripts (without the api_ prefix)
api options are:
--verbose, -v: Verbose mode, show details of the communication
--apiversion, -V <s>: Version of the API to access (default: )
--url, -l <s>: Base URL of CFME to access (default: http://localhost:3000)
--user, -u <s>: User to authentication as (default: admin)
--password, -p <s>: Password for user specified to authenticate as (default: smartvm)
--token, -t <s>: Token to use for authentication instead of user/password (default: )
--format, -f <s>: How to format Json, pretty|none (default: pretty)
--inputfile, -i <s>: File to use as input to the POST/PUT/PATCH methods (default: )
--scriptdir, -s <s>: Directory where optional api_* scripts live (default: /Users/johnhardy/bin)
--version, -e: Print version and exit
--help, -h: Show this message

10. CFME RestAPI Client - 3
To use the CFME RestAPI Client you will need to set the URL to connect to;
--url https://192.168.201.202
Then you set the action (get, post, put, delete etc..)
Lastly set the resource you wish to connect to, the first resource you will want to
investigate will be;
/api
Here is the full example;
./api --url https://192.168.201.202 get /api
Will return all the Resource Collections in the namespace of /api, example few are;
"name": "CFME API",
"description": "ManageIQ Management Engine REST API",
"version": "1.0",
"versions": [
{
"name": "1.0",
"href": "https://192.168.201.202/api/v1.0"
}
],
"collections": [
{
"name": "automation_requests",
"href": "https://192.168.201.202/api/automation_requests",
"description": "Automation Requests"
},
‹#›

11. Supported Authentication
‹#›

12. Technical Syntax
RestAPI – Standard Syntax, All REST is URI based and the construct will always be Actions and
Resources.
Get – Return resource from a webservice.
/api/services – Returns the services.
/api/hosts – Returns the hosts.
Put – Change data in an existing resource.
/api/services/1
{
"name" : "service_1",
"description" : "This is an updated description for the first service"
}
Post – Send a new resource to the webservice.
/api/services/1
{
"action" : "edit",
"resource" : {
"name" : "service_1",
"description" : "This is an updated description for the first service"
}
}
‹#›

13. Technical Syntax
Delete – Delete a resource from a webservice.
/api/services/<id> - Will remove the service from the system.
Patch – Change data in an existing resource.
Supported attribute actions include, add, edit and remove.
/api/services/1
[
{ "action" : "edit", "path" : "name", "value" : "service_001" },
{ "action" : "remove", "path" : "description"}
]
‹#›

14. Querying - 1
‹#›

15. Querying - 1
‹#›

16. Querying - 2
‹#›

17. Technical Syntax - GET
GET /api/<collection>
GET /api/<collection>/<c_id>
GET /api/<collection>/<c_id>/<subcollection>
GET /api/<collection>/<c_id>/<subcollection>/<s_id>
Query VMs
‹#›
- Return first 100 VMs,
- named test*
- displaying name, vendor and guid
- sort by name in ascending order
GET /api/vms?
offset=0&limit=100&
sqlfilter=“name LIKE ‘test*’”&
expand=resources&attributes=name,vendor,guid&
sort_by=name&sort_order=asc
RUBY puts RestClient.get 'https://admin:smartvm@192.168.201.202/api/vms?limit=5&exp
and=resources'
{"name":"vms","count":10,"subcount":5,"resources":[{"id":"https://192.168.201.202/api/vms/118","vendor":"redhat","name":
"All-In-One_0004","location":"fd1e107c-cf4e-4e46-a421-ba8f67c53829.ovf","created_on":"2014-09-02T02:55:18Z","updat
ed_on":"2014-09-02T03:03:42Z","guid":"923e4db4-324c-11e4-9ef3-000c293afc3e","uid_ems":"fd1e107c-cf4e-4e46-a421
-ba8f67c53829","boot_time":"2014-09-02T02:55:34Z","power_state":"unknown","state_changed_on":"2014-09-02T03:03:
42Z","previous_state":"on","connection_state":"connected","template":false,"evm_o

18. Technical Syntax - GET
‹#›
API api get /services
{
"name": "services",
"count": 5,
"subcount": 5,
"resources": [
{
"href": "http://localhost:3000/api/services/225"
},
{
"href": "http://localhost:3000/api/services/221"
},
{
"href": "http://localhost:3000/api/services/227"
},
{
"href": "http://localhost:3000/api/services/226"
},
{
"href": "http://localhost:3000/api/services/228"
}
],
"actions": [
{
"name": "edit",
"method": "post",
"href": "http://localhost:3000/api/services"
},
{
"name": "retire",
"method": "post",
"href": "http://localhost:3000/api/services"
},
{
"name": "delete",
"method": "post",
"href": "http://localhost:3000/api/services"
}
]
}

19. Technical Syntax - GET
CURL curl -k -u admin:smartvm -H "Content-Type: application/json" -X GET https://192.16
‹#›
8.201.202/api/services
{"name":"services","count":5,"subcount":5,"resources":[{"href":"https://192.168.201.202/api/services/225"},{"href":"https://192.168.201.202/api/servi
ces/221"},{"href":"https://192.168.201.202/api/services/227"},{"href":"https://192.168.201.202/api/services/226"},{"href":"https://192.168.201.202/ap
i/services/228"}],"actions":[{"name":"edit","method":"post","href":"https://192.168.201.202/api/services"},{"name":"retire","method":"post","href":"http
s://192.168.201.202/api/services"},{"name":"delete","method":"post","href":"https://192.168.201.202/api/services"}]}

20. Technical Syntax - GET
SOAPui
‹#›
Endpoint : https://192.168.201.202
Resource : /api/services
Authentication : basic

21. Technical Syntax - POST
POST /api/<collection> - Targeting multiple resources
POST /api/<collection>/<c_id> - Targeting a single resource
POST /api/<collection>/<c_id>/<sub_collection> - Targeting multiple sub-resources
POST /api/<collection>/<c_id>/<sub_collection>/<s_id> - Targeting a single sub-resource
POST /api/<collection>
{
“action” : <name_of_action>,
“resources” : [
{
‹#›
“href” : HREF_for_resource_a,
<attr> : <value>,
…
},
{
“href” : HREF_for_resource_b,
<attr> : <value>,
},
…
]
}

22. Technical Syntax - POST
Ordering multiple services 3 & 4 from a service catalog 2
POST /api/service_catalogs/2/service_templates
{
"action" : "order",
"resources" : [
{
"href" : “http://localhost:3000/api/service_templates/3”,
"option_1_vm_target_name" : "sample-vm-1201",
"option_2_vm_target_hostname" : "sample-vm-1201"
},
{
"href" : "http://localhost:3000/api/service_templates/3",
"option_1_vm_target_name" : "sample-vm-1202",
"option_2_vm_target_hostname" : "sample-vm-1202"
},
{
"href" : "http://localhost:3000/api/service_templates/4",
"option_1_vm_target_name" : "dev-vm1",
"option_2_vm_target_hostname" : "dev-vm1",
"option_3_vm_memory" : '16384'
},
]
}
‹#›

23. Technical Syntax - POST
RUBY
‹#›
require 'rest-client'
require 'json'
puts RestClient.post 'https://admin:smartvm@192.168.201.202/api/service_catalogs/1/ser
vice_templates',
{:action => "order",
:resources => [{
:href => "https://192.168.201.202/api/service_catalogs/1/service
_templates/5",
:sshUser => "OSEroot",
:rebootServers => "false"
}]
}.to_json
{"results":[{"approval_state":"pending_approval","created_on":"2014-09-10T09:09:43Z","descripti
on":"Provisioning Service [OpenShift All-In-One] from [JOpenShift All-In-One]","destination_id":n
ull,"destination_type":null,"fulfilled_on":null,"id":188,"message":"Service_Template_Provisioning
- Request Created","options":{"dialog":{"dialog_sshUser":"OSEroot","dialog_rebootServers":"fals
e"}},"request_state":"pending","request_type":"clone_to_service","requester_id":1,"requester_na
me":"Administrator","source_id":5,"source_type":"ServiceTemplate","status":"Ok","updated_on":"
2014-09-10T09:09:43Z","userid":"admin"}]}

24. Technical Syntax - POST
CURL
‹#›
curl -k -u admin:smartvm -H "Content-Type: application/json" -X POST https://192.1
68.201.202/api/service_catalogs/1/service_templates -d '{ "action":"order","resource
s":[{"href":"https://192.168.201.202/api/service_catalogs/1/service_templates/5","ssh
User":"OSEroot","rebootServers":"false"}]}'
{"results":[{"approval_state":"pending_approval","created_on":"2014-09-10T15:12:01Z","descripti
on":"Provisioning Service [JOpenShift All-In-One] from [JOpenShift All-In-One]","destination_id":
null,"destination_type":null,"fulfilled_on":null,"id":195,"message":"Service_Template_Provisioning
- Request Created","options":{"dialog":{"dialog_sshUser":"OSEroot","dialog_rebootServers":"fals
e"}},"request_state":"pending","request_type":"clone_to_service","requester_id":1,"requester_na
me":"Administrator","source_id":5,"source_type":"ServiceTemplate","status":"Ok","updated_on":"
2014-09-10T15:12:03Z","userid":"admin"}]}

25. Technical Syntax - PUT
PUT /api/<collection>/<c_id> - Targeting a single resource
{
<attr_1> : <value_1>,
<attr_2> : <value_2>,
…
}
Updating attributes of service 1
PUT /api/services/1
{
"name" : "service_1",
"description" : "This is an updated description for the first service"
}
‹#›

26. Technical Syntax - PUT
RUBY
‹#›
require 'rest-client'
require 'json'
result = RestClient.get 'https://admin:smartvm@192.168.201.202/api/services/223'
entity = JSON.parse(result)
puts "Old Name = #{entity['name']}"
newname = "OpenShift All-In-One"
puts RestClient.put 'https://admin:smartvm@192.168.201.202/api/services/223',{
:name => newname
}.to_json
result = RestClient.get 'https://admin:smartvm@192.168.201.202/api/services/223'
entity = JSON.parse(result)
puts "NEW Name = #{entity['name']}"
Old Name = TEST
{"id":"https://192.168.201.202/api/services/223","name":"OpenShift All-In-One","description":"Re
d Hat OpenShift Enterprise All-In-One Installation","guid":"d399812e-38c9-11e4-b079-000c293af
c3e","service_template_id":5,"options":{"button_order":["cb-3"]},"display":true,"created_at":"2014
-09-10T09:07:01Z","updated_at":"2014-09-10T09:26:29Z","evm_owner_id":1,"miq_group_id":1}
NEW Name = OpenShift All-In-One

27. Technical Syntax - PATCH
PATCH /api/<collection>/<c_id> - Patching a single resource
[
{ “action” : “edit”, “path” : <attr_1>, “value” : <value_1> },
{ “action” : “add” , “path” : <attr_2>, “value” : <value_2> },
{ “action” : “remove”, “path” : <attr_3>},
…
]
Patching some attributes of service 1
PATCH /api/services/1
[
{ “action” : “edit”, “path” : “name”, “value” : “service_0001”,
{ “action” : “remove”, “path” : “description”}
]
‹#›

28. Technical Syntax - DELETE
DELETE /api/<collection>/<c_id> - Deleting a single resource
POST /api/<collection>/<c_id> - Deleting a single resource via the delete action
POST /api/<collection> - Deleting multiple resources via the delete action
Delete service 1
DELETE /api/services/1
Delete services 5 & 6
POST /api/services
{
“action” : “delete”,
“resources” : [
{ “href” : “http://localhost:3000/api/services/5” },
{ “href” : “http://localhost:3000/api/services/6 }
]
}
‹#›

29. Technical Syntax - DELETE
Single Request
RUBY
Multi Request
‹#›
require 'rest-client'
require 'json'
puts RestClient.post 'https://admin:smartvm@192.168.201.202/api/services/223'
Process finished with exit code 0
RUBY
require 'rest-client'
require 'json'
puts RestClient.post 'https://admin:smartvm@192.168.201.202/api/services',
{:action => "delete",
:resources => [{
:href => "https://192.168.201.202/api/services/219",
:href => "https://192.168.201.202/api/services/222",
}]
}.to_json
{"results":[{"created_at":"2014-09-02T16:15:39Z","description":"Red Hat OpenShift Enterprise All-In-One Installa
tion","display":true,"evm_owner_id":1,"guid":"6169987c-32bc-11e4-8e93-000c293afc3e","id":219,"miq_group_id
":1,"name":"OpenShift All-In-One","options":{"button_order":["cb-3"]},"retired":null,"retirement_last_warn":null
,"retirement_state":null,"retirement_warn":null,"retires_on":null,"service_id":null,"service_template_id":5,"upd
ated_at":"2014-09-02T16:15:39Z"}]} Process finished with exit code 0

30. Automation Request
Trigger an Automation 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
}
"requester" : {
"user_name" : "jdoe",
"auto_approve" : true
}
}
‹#›

31. Technical Syntax – Automation Request
RUBY
‹#›
require 'rest-client'
require 'json'
puts RestClient.post 'https://admin:smartvm@192.168.201.202/api/automation_requests',
{:version => "1.1",
:uri_parts => [{
:namespace => "System",
:class => "Request",
:instance => "InspectME",
:message => "create"
}],
:paramters => [{
:attribute1 => "value1",
:attribute2 => "value2"
}],
}.to_json
{"results":[{"approval_state":"pending_approval","created_on":"2014-09-10T10:20:16Z","
description":"Automation Task","destination_id":null,"destination_type":null,"fulfilled_on
":null,"id":194,"message":null,"options":{"namespace":"SYSTEM","class_name":"PROC
ESS","instance_name":"AUTOMATION_REQUEST","user_id":1,"attrs":{"userid":"admin"}
},"request_state":"pending","request_type":"automation","requester_id":1,"requester_na
me":"Administrator","source_id":null,"source_type":null,"status":"Ok","updated_on":"20
14-09-10T10:20:16Z","userid":"admin"}]}

32. Provisioning Request
Trigger a Provisioning Request
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" : "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" : { }
}
‹#›

33. Technical Syntax – Provisioning Request
RUBY
‹#›
require 'rest-client'
require 'json'
puts RestClient.post 'https://admin:smartvm@192.168.201.202/api/automation_requests',
{:version => "1.1",
:template_fields => { :guid => "3fac48b0-312c-11e4-84f0-000c293afc3e"},
:vm_fields => {
:number_of_cpus => 1,
:vm_name => "RestAPItest",
:vm_memory => "1024",
:vlan => "rhevm"
},
:requester => {
:user_name => "admin",
:owner_first_name => "John",
:owner_last_name => "Hardy",
:owner_email => "jhardy@redhat.com",
:auto_approve => "false"
},
:tags => {
:network_location => "internal",
:cc => "001"
},
:addtional_values => {},
:ems_custom_attributes => {},
:miq_custom_attributes => {},
}.to_json
{"results":[{"approval_state":"pending_approval","created_on":"2014-09-10T10:20:16Z","description":"
Automation Task","destination_id":null,"destination_type":null,"fulfilled_on":null,"id":194,"message":n
ull,"options":{"namespace":"SYSTEM","class_name":"PROCESS","instance_name":"AUTOMATION_R
EQUEST","user_id":1,"attrs":{"userid":"admin"}},"request_state":"pending","request_type":"automatio
n","requester_id":1,"requester_name":"Administrator","source_id":null,"source_type":null,"status":"O
k","updated_on":"2014-09-10T10:20:16Z","userid":"admin"}]}

34. Gotchas
• Create Group
• Create Role
• Add Provider
• Create Policy (assign Tag)
• Assign policy (to provider)
• VM Operations = (start/stop/delete)
• Add collection for Cloud and Service Workloads (Instance/Image/AZ,
‹#›
Security Group, VPC, Subnet)
• Collection relationships (ex: IP/.…)
• Invoke a task associated with a deployed Service
• Query tags for friendly names.

35. Gotchas
Currently the RestAPI does not offer functions for;
Categories/Tags – Create or Delete is absent.
Workaround – Simply write the Create/Delete Category or Tag
‹#›
functions as a method using the standard built-in commands
such as “$evm.execute(‘category_create’,……) Call this method
from a RestAPI resource “Automation Request”

36. Further Information
The RestAPI documentation is available here;
https://github.com/ManageIQ/guides/tree/master/rest_api
The current version of the RestAPI is version 1.0
The design specification can be found here;
https://github.com/ManageIQ/guides/blob/master/rest_api/
‹#›
design.md

37. ‹#›
Q & A
Blog – cloudformsnow.com
YouTube -
https://www.youtube.com/user/cloudfor
msnow