In this recipe, we are looking at how to access and play with the Orchestrator REST API.
Getting ready
We need a browser, preferably Chrome or Firefox.
To play and explore, we also need access to the Orchestrator Control Center.
We will be using the example workflow 07.02 Access via PowerShell (Input).
How to do it...
The recipe is broken up into multiple parts for easier reading; the best way forward is to work through one after the other.
Accessing the API documentation and enable "play mode"
Note
Please note that this is a stetting that you shouldn't use in any production environments.
Open the Orchestrator Control Center and enter the system property com.vmware.o11n.sso.basic-authentication.enabled = true as shown in section System properties in the recipe Control Center titbits in Chapter 2, Optimizing Orchestrator Configuration.
Open a browser and browse to https://[Orchestrator]:8281/vco/api/docs/
The SwaggerUI of Orchestrator will open up.
Try it out!
Let's give it a quick go:
Navigate to service-descriptor-controller and click on it.
A lot of functions should show up. Click on /api/about:
Scroll down a bit and then click on Try it out!
You should now see the result of your REST request:
Interactive REST request
We will now request information using some inputs:
Go to and expand workflow-controller.
Select Post /api/workflows/{workflowId}/executions.
Under workflowID, enter bb7bcb76-515e-4fdb-80e3-63227ad0cfd0, which is the ID of the example workflow, 07.02 Access via PowerShell (Input).
Click on the eggshell colored field on the left side. This will fill the basic template into the white right field (number 12).
Make sure that the Parameter content type is set to application/json.
Scroll down and click on Try it out!
If you now check in Orchestrator you see that the workflow was run.
Scroll down: you will see that you didn't get an output. For that, you need to look at the workflow execution, the same as you would by using the Orchestrator Client.
Have a closer look at the Response headers. You'll find a key called location and behind it, a URL. This is the response URL to the execution you triggered. It contains the Workflow ID and the Execution ID:
Scroll further down to get /api/workflows/{workflowId}/executions/{executionId}.
Copy the Workflow ID and the Execution ID from the response URL into the required fields and then click on Try it out!.
The Response Body now shows a JSON object that contains all the links to more information, such as the logs, but it also contains the output parameters that contain the return values of our workflow:
We are finished with the showcase; you might want to reverse the system property you set up in the first section of this recipe.
How it works...
The Orchestrator REST API is the central point of contact for everything Orchestrator. If you understand how to work the API you can use any programming language to connect and run the workflows.
When you run a workflow, you POST the parameters you need in the BODY of the message to the correct URL. If you don't have any parameters, such as in our first example, you POST an empty JSON body {}.
Orchestrator will now run the workflow and store all the parameters (in, out and attributes) as well as the logs with the workflow execution. The return value of the post will contain the current status of the workflow execution (running, completed) as well as the response URL. The response URL consist of the workflow ID and the execution ID:
If you now GET the response URL you will receive all the information that the workflow execution contains as JSON.
There's more...
The XSD for the Orchestrator API can be found here:https://[Orchestrator]:8281/vco/api/docs/o11n-sdk-rest.xsd
See also
To further explore the REST API, have a look at the following recipes:
Running Orchestrator workflows using PowerShell in this chapter