Just played with vCenter Orchestrator REST APIs and found it’s pretty straight-forward to use. With the REST APIs, you can manage various resources such as workflow, workflow run, workflow presentation, workflow user interaction presentation, catalog, action, package, inventory, action, category, configuration, content, notification, service descriptor, user. It seems possible to build your vCO client like GUI with this set of APIs.
API Documentation Included
Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.
With vCO installation, you can access the REST API documentation easily with the following URL. Note that http://192.168.8.8:8280/api/docs/ also works but it redirects to the HTTPS link as follows.
The page has links to the REST API services, Data Model, and Files and Libraries. Very helpful and convenient indeed.
Executing Workflows Remotely
While you can interact with various services from vCO, the most common one is to remotely call existing workflows. This is achieved by the Workflow Run Service which includes several operations like retrieving all workflow runs, starting workflow in a new run, finding out the running status of a workflow run, retrieving logs.
What I care the most is to run a workflow. It can be done using HTTP POST with REST client add-on Firefox browser.
POST https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/executions Header: Content-Type: application/xml Body: <execution-context xmlns="http://www.vmware.com/vco"> <parameters> </parameters> </execution-context>
The 192.168.8.8 is the static IP address of vCO server, and the 29b6dfb4-2942-4bc0-b544-c8383d979572 is the id for the workflow you intend to run. Note: you have to use https protocol or you will receive same response as GET and the workflow would not run at all.
If you have parameters to pass into the workflow, you want to include them within the
<parameter name="dcName" type="string"> <string>Santa Clara</string> </parameter> <parameter name="cluster" type="string"> <string>Demo Sandbox</string> </parameter>
After running the API call, you will get a response with code 202 as follows:
Status Code: 202 Accepted Content-Length: 0 Date: Tue, 06 Aug 2013 23:37:06 GMT Etag: "0d41d8cd98f00b204e9800998ecf8427e" Location: https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/executions/ff8080814017b877014055fdbb01089 3/ Server: vCO Server
Find Workflow ID Using Name
You may wonder, “how can I find the id string for the workflow even though I know its name?”
A fair question. To get the id, you want to list all the workflows via HTTP GET method.
It may take several seconds before the call returns with the following the header – all depends on how many workflows you have in vCO server.
Status Code: 200 OK Cache-Control: no-cache Content-Length: 227041 Content-Type: application/xhtml+xml;charset=UTF-8 Date: Wed, 07 Aug 2013 17:16:53 GMT Etag: "0ffdf5134a56fa98d2898883caee557c9" Expires: Thu, 01 Jan 1970 00:00:00 UTC Pragma: No-cache Server: vCO Server
The interesting part is the response body which looks like the following. Since the real XML is pretty long, I just list part of it with clear structure.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <inventory-items xmlns="http://www.vmware.com/vco" total="247"> <link rel="down" href="https://192.168.8.8:8281/api/workflows/51808080808080808080808080808080A180808001175587494510271f02ffa1f/"> <attributes> <attribute name="itemHref" value="https://192.168.8.8:8281/api/workflows/51808080808080808080808080808080A180808001175587494510271f02ffa1f/"/> <attribute name="id" value="51808080808080808080808080808080A180808001175587494510271f02ffa1f"/> <attribute name="categoryName" value="Samples XML (Simple)"/> <attribute name="canExecute" value="true"/> <attribute name="categoryHref" value="https://192.168.8.8:8281/api/catalog/System/WorkflowCategory/ff8080813fc58b2b013fc58b69ef0004/"/> <attribute name="description" value="Creates a simple XML document for testing purposes."/> <attribute name="name" value="Create a simple XML document"/> <attribute name="type" value="Workflow"/> <attribute name="canEdit" value="true"/> </attributes> </link> ... <link rel="down" href="https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/"> <attributes> <attribute name="itemHref" value="https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/"/> <attribute name="id" value="29b6dfb4-2942-4bc0-b544-c8383d979572"/> <attribute name="categoryName" value="MyWF"/> <attribute name="canExecute" value="true"/> <attribute name="categoryHref" value="https://192.168.8.8:8281/api/catalog/System/WorkflowCategory/ff8080813fc58c21013fca524c7d0004/"/> <attribute name="description" value=""/> <attribute name="name" value="HelloWorld"/> <attribute name="type" value="Workflow"/> <attribute name="canEdit" value="true"/> </attributes> </link> </inventory-items>
With the above XML, you can easily retrieve the ID of an existing workflow if you know its name.