Design Summit - RESTful API Overview - John Hardy

‹#›

ManageIQ RestAPI

John HardyJohn HardyProduct Manager

Fall 2014

‹#›

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

‹#›

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.

‹#›

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.

‹#›

Use Cases - 1

Northbound and Southbound interfacing.

We are automatedITSM 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.

‹#›

Use Cases – 2

Northbound and Southbound interfacing.

We automateManageIQ 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.

‹#›

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.

http://localhost:3000/api/services

‹#›

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

‹#›

CFME RestAPI Client - 2api 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

‹#›

CFME RestAPI Client - 3To 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"

},

https://192.168.201.202

‹#›

Supported Authentication

‹#›

Technical SyntaxRestAPI – 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" : {



}

}

‹#›

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"}

]

‹#›

Querying - 1

‹#›

Querying - 1

‹#›

Querying - 2

‹#›

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

RUBYputs RestClient.get 'https://admin:[email protected]/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","updated_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

‹#›


API api get /services

{"name": "services","count": 5,"subcount": 5,"resources": [{

"href": "http://localhost:3000/api/services/225"},{




"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"

}]

}

‹#›


CURLcurl -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"}]}

‹#›


SOAPuiEndpoint : https://192.168.201.202Resource : /api/servicesAuthentication : basic

https://192.168.201.202

‹#›

Technical Syntax - POST

POST /api/<collection> - Targeting multiple resourcesPOST /api/<collection>/<c_id> - Targeting a single resourcePOST /api/<collection>/<c_id>/<sub_collection> - Targeting multiple sub-resourcesPOST /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>,

},

…

]

}

‹#›


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'

},

]

}

‹#›


RUBY

require 'rest-client'require 'json'

puts RestClient.post 'https://admin:[email protected]/api/service_catalogs/1/service_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"}]}

‹#›


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

‹#›

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

{



}

‹#›

Technical Syntax - PUT

RUBY


result = RestClient.get 'https://admin:[email protected]/api/services/223'entity = JSON.parse(result)puts "Old Name = #{entity['name']}"

newname = "OpenShift All-In-One"

puts RestClient.put 'https://admin:[email protected]/api/services/223',{:name => newname

}.to_json

result = RestClient.get 'https://admin:[email protected]/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

‹#›

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”}

]

‹#›

Technical Syntax - DELETE

DELETE /api/<collection>/<c_id> - Deleting a single resourcePOST /api/<collection>/<c_id> - Deleting a single resource via the delete actionPOST /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 }

]

}

http://localhost:3000/api/services/5

http://localhost:3000/api/services/6

‹#›

Technical Syntax - DELETE

RUBY


puts RestClient.post 'https://admin:[email protected]/api/services/223'

Process finished with exit code 0

Single Request

RUBY

require 'rest-client'

require 'json'

puts RestClient.post 'https://admin:[email protected]/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 Installation","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,"updated_at":"2014-09-02T16:15:39Z"}]} Process finished with exit code 0

Multi Request

‹#›

Automation RequestTrigger 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

}

}

‹#›

Technical Syntax – Automation Request

RUBY


puts RestClient.post 'https://admin:[email protected]/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"}]}

‹#›

Provisioning RequestTrigger 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" : "[email protected]",

"auto_approve" : true

},

"tags" : { "network_location" : “Internal", "cc" : “001” },

"additional_values" : { "request_id" : “1001” },

"ems_custom_attributes" : { },

"miq_custom_attributes" : { }

}

‹#›

Technical Syntax – Provisioning Request

RUBY


puts RestClient.post 'https://admin:[email protected]/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 => "[email protected]",: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":null,"options":{"namespace":"SYSTEM","class_name":"PROCESS","instance_name":"AUTOMATION_REQUEST","user_id":1,"attrs":{"userid":"admin"}},"request_state":"pending","request_type":"automation","requester_id":1,"requester_name":"Administrator","source_id":null,"source_type":null,"status":"Ok","updated_on":"2014-09-10T10:20:16Z","userid":"admin"}]}

‹#›

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.

‹#›

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”

‹#›

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

https://github.com/ManageIQ/guides/tree/master/rest_api

https://github.com/ManageIQ/guides/blob/master/rest_api/design.md

‹#›

Q & A

Blog – cloudformsnow.com

YouTube -https://www.youtube.com/user/cloudfor

msnow

Design Summit - RESTful API Overview - John Hardy

Technology