Introducing Swagger UI on vRO 7.0.1

Although vRealize Orchestrator (vRO) has provided API documentation built-in to the server, it was static content that could not be quickly used for tests or building queries. When a product provides a nice API explorer that not only tells you the available urls and basic docs, but also provides a web-based UI that allows you to quickly build up custom calls and shows you the generated content, the consumption and integration time for developers is reduced considerably. This article will provide a brief introduction to Orchestrator’s latest API Documentation feature: Swagger !

Browse to the API Docs on your vRO Server

browse_to_the_api_docs_on_your_vro_server.png
As with past versions of vRO, visit the built-in API docs at: https://vro7:8281/vco/api/docs/

Once the page loads, you’ll be presented with a page a bit different than what you may have seen in past versions of the API docs for Orchestrator…

If you are using a Standalone vRO 7.0.1 Appliance, no additional steps are required in order to begin using the Swagger UI that is seen further down the page. If, however, you happen to be trying this out on a vRO server that has been configured for SSO then you’ll need to add the line com.vmware.o11n.sso.basic-authentication.enabled=true to the /etc/vco/app-server/vmo.properties file as indicated on the API Documentation page shown here. You may need to restart the vco-server service (I’m not sure because the server I’m testing with is not using SSO.)

NOTE: For the duration of this article, my vRO Hostname is vro7

Scroll down to the Swagger Interface

scroll_down_to_the_swagger_interface.png
Scroll down the page until you see the API Services listing shown here.

You can learn more about the available Operations for each service by clicking any of them… let’s click on the workflow-service (can click Show/Hide, List Operations) to get the next screen as well…

workflow-service

workflow-service.png
As you can see, there are a number of operations available for the Workflow Service.

When dealing with the Orchestrator API, one of the first things someone wants to do is get a workflow so let’s try that.

Click the GET /api/workflows link to expand that operation

media_1460670305634.png
Look at that! A form to help you create your query.

At this point, even a fresh install of Orchestrator has 100s of workflows so before we try out this form, change the maxResult box to a smaller number - I’ll set mine to 20

Click the Try it out! button when you’re ready.

Credentials Required!

credentials_required_.png
If you have not already authenticated to your vRO Server you’ll need to provide credentials now. Since I’m using a standalone server, not exposed anywhere I just enter the default vcoadmin/vcoadmin as my credentials and click OK

Response

response.png
Note that the Request URL has been generated with the parameters added. The extra & at the end are due to not adding values to all the other form fields. They do not affect anything.

You’re also provided with the Response Body, Code, and Headers. All of this can be very helpful when coding your system/script to call an Orchestrator workflow.

Let’s try using a condition to search for a specific workflow…..

Find a specific workflow using a condition

find_a_specific_workflow_using_a_condition.png
Here, I have added the condition name=Hello World - Custom since that is the workflow I would like to find. If you wished to use multiple conditions to further narrow down results, specify them in that same box just delimit each key=value pair with a comma. For example, in this VMware Communities post, I used the following as condition: name=Management,vimHost=https://vcsa-01a.corp.local:443/sdk because my results had two different vCenters with a “Management” folder for vms.

Results

results.png
Here, the Response URL was built like this: plain https://vro7:8281/vco/api/workflows?maxResult=20&startIndex=0&queryCount=false&&conditions=name%3DHello%20World%20-%20Custom&&

We can clean that up a little by removing the maxResult, startIndex, queryCount, and the extra && at the end: plain https://vro7:8281/vco/api/workflows?conditions=name%3DHello%20World%20-%20Custom

In the Response Body, we can see the URL to access that workflow as well as various attributes for that workflow, including its ID: 20923da9-20c5-451e-9ead-5285186e93a5 …

One of the other operations available from the Swagger UI is GET /api/workflows/{id} which Retrieves the definition of a workflow. Let’s take a look at that now. Copy the ID you got from the workflow you searched for (you can’t use mine because you don’t have my workflow!)

Wait a sec - all that work to get a workflow ID? Isn’t there an easier way?

wait_a_sec_-_all_that_work_to_get_a_workflow_id_isn_t_the.png
Yes, that was a lot of clicking around, but the purpose here is to introduce Swagger ;)

If you want/need to get a workflow ID, the easiest way is to simply open your vRO Client, select the workflow you wish to interact with via the API….

Click the General tab, then highlight and copy the ID value as shown in this screenshot!

Back to Swagger - Get a workflow definition

back_to_swagger_-_get_a_workflow_definition.png
So now that we have a workflow id in our clipboard, expand out the GET /api/workflows/{id} operation and paste the ID into the field as shown above and click Try it Out!

Response - Workflow definition

response_-_workflow_definition.png
As you can see, the Request URL is the same as the HREF we saw in the last form. The important stuff here is the Response Body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
"href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/",
"relations": {
"link": [
  {
  "href": "https://vro7:8281/vco/api/inventory/System/Workflows/vCO%2BMaster%2BClass%2BLab%2BSolutions/",
  "rel": "up"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/executions/",
  "rel": "executions"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/presentation/",
  "rel": "presentation"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/tasks/",
  "rel": "tasks"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/icon/",
  "rel": "icon"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/schema/",
  "rel": "schema"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/permissions/",
  "rel": "permissions"
  },{
  "href": "https://vro7:8281/vco/api/workflows/20923da9-20c5-451e-9ead-5285186e93a5/interactions/",
  "rel": "interactions"
  }
]
},
"id": "20923da9-20c5-451e-9ead-5285186e93a5",
"customized-icon": false,
"name": "Hello World - Custom",
"version": "0.0.0",
"description": "",
"input-parameters": [
  {
  "description": "Given Name (First Name)",
  "type": "string",
  "name": "firstName"
  },{
  "description": "Surname (Last Name)",
  "type": "string",
  "name": "lastName"
  }
],
"output-parameters": [
  {
  "description": "Complete salutation line",
  "type": "string",
  "name": "salutation"
  }
]
}

So at this point, you can reference my older, but still relevant, article on interacting with Orchestrator via REST.

Summary

As you can see from the very brief introduction here, Swagger can be very helpful in determining the correct format of a request URL for your REST calls for scripts and integrations. When I came across this new feature today, I was very pleasantly surprised since it did not appear in any official documentation around vRO 7.0.1 such as the Release Notes or Developing a Web Services Client for VMware vRealize Orchestrator. If “swagger” appears in either of these locations when you are reading this, they have been added after this article was written.

Please explore this feature and share your findings!

Enjoy!