Using OpenAPI in vRealize Orchestrator HTTP REST Plug-in

Introduction

vRealize Orchestrator ships with many plug-ins by default. Every plug-in solves a particular problem and it does it well. This blogpost targets one of the most used vRealize Orchestrator plug-ins – the HTTP REST Plug-in. Assuming that the reader is familiar with the core concepts of the plug-in such as REST Host, REST Operation and OpenAPI we’re going to target the out of the box functionalities which the plug-in provides around OpenAPI as we also explore some general vRealize Orchestrator scenarios. We’ll see an alternative approach for creating REST hosts by leveraging the OpenAPI Specification (OAS) and the usage of the HTTP REST Plug-in scripting objects while implementing our own custom workflow.

Any service that exposes OpenAPI Specification via REST API is subject to the creation of REST hosts. Compared to a manually created REST Host, a Swagger REST Host comes with pre-configured operations which greatly minimises the risk of misconfiguration when manually adding every operation. This greatly improves the versatility of the Swagger REST Host as it can be recreated in any instance of vRealize Orchestrator with a few clicks. The plug-in comes with two workflows that support both specification versions Swagger 2.0 and OpenAPI 3.0. Those workflows are the building blocks for creating REST Hosts from systems that support OpenAPI specification.

What are Swagger and OpenAPI?

OpenAPI is the de-facto standard for describing, producing, consuming and visualising REST APIs.

“The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.”

OpenAPI Specification docs – https://swagger.io/specification/

There are few things we should clear out to avoid confusion:

• Swagger 2.0 is OpenAPI Specification version 2.0
• OpenAPI 3.0 is OpenAPI Specification version 3.0
• Swagger usually refers to the tools used to interact with the OpenAPI Specification

For the purpose of this blogpost we will use Swagger and OpenAPI interchangeably.

Creating REST Host from Swagger Endpoint

The easiest way to create a REST Host through OpenAPI spec is by using the Add a REST Host by Swagger spec from a URL workflow. This workflow can only be used with an endpoint that returns a Swagger or OpenAPI specification string. For this example we’ll use a service called Swagger Schema Registry Service (SSRS). This is Spring Boot web application that we will run as a local service. Our goal is to create a REST Host from the OpenAPI spec that the service provides.

Prerequisites

• SSRS demo service
• Latest vRealize Orchestrator HTTP REST Plug-in

Let’s start off by opening our vRealize Orchestrator web UI -> Expand Library -> Click on Workflows -> Write swagger in the search box. This will display the Swagger workflows that come out of the box with the HTTP REST Plug-in.

Click Run on the Add a REST host by Swagger spec from a URL workflow and the tab below will pop-up.

REST Hosts are highly customisable as they have an abundance of options we can choose from. For our scenario we’ll focus only on those 3 fields:

• Name
• Swagger Spec URL
• Swagger/OpenAPI version

SSRS exposes OpenAPI 3.0 schema so we will select OpenAPI 3.x from the Swagger/OpenAPI version dropdown field. Our final input should look like the picture below. Keep in mind that the ip address we are using as an input parameter will differ as we are running SSRS on local machine.

What each field means:

• Name – this is the name of the REST Host we want to create, this name will be displayed when we expand the vRealize Orchestrator inventory
• Swagger Spec URL – this field is the URL to the service where the OpenAPI specification lives
• Swagger/OpenAPI version – this field is very important as some services might still be on Swagger version 2.0, here we can select which version of the OAS we’ll be fetching in order for the HTTP REST Plugin to create that REST Host

After we execute the workflow we should get status Completed, this indicates that the REST Host has been added successfully.

There is one more thing we can do to ensure that the REST Host was added successfully and that is by navigating to the Inventory tab which is under Administration.

When we expand the HTTP-REST inventory item we will see that REST Host was successfully added with all of its operations that were defined in the OpenAPI schema. These operations represent endpoints we can execute requests against.

Great! We’ve created our first REST Host from OpenAPI specification. This Swagger REST Host works like any other REST Host. You can find out more about using REST Hosts in the plug-in documentation.

Extending vRealize Orchestrator with custom workflow

Let’s spice up our blogpost with few more examples.

Having a swagger specification referencing other swagger specifications is a common use case. We can dive further into that and create a custom workflow that would allow us to create multiple Swagger REST Hosts from a single Swagger REST Host.

In the previous example we created Swagger REST Host from SSRS. This REST Host actually contains endpoints to other swagger schemas. While we can go and invoke all the REST Operations that our Swagger Host has and create other Swagger REST Hosts from the result that would be cumbersome because we have to do it manually and it will hinder our ability to migrate many swagger hosts to another instance of vRealize Orchestrator quickly. Keep in mind that we should already have a service that exposes swagger schemas through REST endpoints, which is our Swagger Schema Registry Service (SSRS). We will only focus on consuming this service, as we will create workflow to create REST Hosts based on the SSRS schemas. Here is a diagram that explains the SSRS better:

Our SSRS exposes an OpenAPI schema which has 2 endpoints – one that points to the Petstore Swagger 2.0 schema and another that points to the Petstore OpenAPI 3.0 schema. We have everything we need, so let’s get started.

Go back to the Workflow inventory and click on the new workflow button.

Let’s name our workflow Create REST Hosts from Swagger Schema Registry Service.

We’ll create two new variables that we’ll use in our scriptable tasks. The first variable operations is responsible for collecting all the operations that are in our Swagger REST Host which we’ll pass as an input parameter. The second variable operationsResult is responsible for collecting the results from the executed operations. More implementation details can be found in the scriptable tasks we’ll create in a moment.

We’ll create an input for the REST Host and call it selectedRESTHost. The other field operationParams will be auto-generated later when we create Foreach Element however, we shouldn’t put big emphasis on it.

The selectedRESTHost input field that we created also created an input in our Input Form. We can just call it REST Host. This input field would allow us to select our Swagger Schema Registry Service REST Host.

Our canvas would consist of three elements – two Scriptable Tasks and one Foreach Element. Again we’ll go thoroughly through each one.

The first Scriptable Task Get REST Host Operations would allow us to populate the operations variable that we created earlier. We’ll pass this variable to our next element in the canvas which is Invoke all REST operations.

// [Get REST Host Operations]

// populate array with REST Operations
operations = []

var operationIds = selectedRESTHost.getOperations()

for (var index in operationIds) {
    // get operation by id
    var operation = selectedRESTHost.getOperation(operationIds[index])

    System.log("Adding operation to operations list: " + operation.name)

    operations.push(operation)
}

operationsOut = operations

What Invoke all REST operations will help us achieve is to execute requests against all the endpoints which were created for our schema-registry-host. Those endpoints will give us the Swagger/OpenAPI schemas from the Swagger Schema Registry Service. We’ll pass the operations array as a For each item in array and Invoke a REST operation as workflow.

Our most important piece of content would be the Create Swagger/OpenAPI Hosts scriptable task. This is where all the magic happens and we use the responses generated from the Invoke all REST operations workflow to create REST Hosts.

// [Create Swagger/OpenAPI Hosts]

var schemas = []

for (var index in operationsResult) {

    // adding the swagger/openapi schema strings that were aggregated in 'Get REST Host Operations'
    schemas.push(operationsResult[index].contentAsString)
}

// REST Hosts that will be generated from the openapi/swagger schemas
var generatedHosts = []

for (var i = 0; i < schemas.length; i++) {

    var host;

    host = createRESTHostFrom("openapi", schemas[i]);

    if (host == null) {
        host = createRESTHostFrom("swagger", schemas[i])
    }

    generatedHosts.push(host);
}

for (var index in generatedHosts) {
    RESTHostManager.addHost(generatedHosts[index])
}

for (var index in generatedHosts) {

    var hostUrl = generatedHosts[index].url;

    // checks if https exists in hostUrl
    if ((/^https:/).test(hostUrl)) {

        System.log("Importing certificate from url: " + hostUrl);

        importCertificateFrom(hostUrl);
    }
}

function importCertificateFrom(url) {

    var importCertFromUrlWf = System.getModule("com.vmware.library.workflow").getWorkflowById("c5a874a2-e8e7-480d-bdde-d1a80b8a3011");

    var workflowParameters = new Properties();

    workflowParameters.put("url", url);
    workflowParameters.put("ignoreWarnings", true);

    var token = importCertFromUrlWf.execute(workflowParameters);

    System.getModule("com.vmware.library.workflow").waitAllWorkflowComplete([token]);
}

function createRESTHostFrom(swaggerVersion, schema) {
    var host;

    try {
        System.log("Trying to create REST Host from " + swaggerVersion + " schema string...")

        if (swaggerVersion == "openapi") {

            host = RESTHostManager.createRESTHostFromOpenApiSpecString("generated-oas-host-" + i, schemas[i], null, null);

        } else if (swaggerVersion == "swagger") {

            host = RESTHostManager.createRESTHostFromSwaggerSpecString("generated-swagger-host-" + i, schemas[i], null, null);
        }

        System.log("Successfully created REST Host from " + swaggerVersion + " schema string: " + host)
    } catch (ex) {
        System.log("Could not create a REST Host from " + swaggerVersion + " spec string: " + ex);
    }

    return host
}

Let’s execute our workflow and see what happens. Click Run then select the schema-registry-host and execute the workflow.

The workflow should have completed successfully. Navigating back again to our Inventory and see what’s in there.

If we expand one of our generated REST Hosts we’ll see how much time we saved for ourselves by generating such complex host in few clicks.

Amazing! Now we have a bunch of hosts that have been generated from our Swagger Schema Registry Service.

One last thing we must do to ensure that our generated REST Hosts work properly is to invoke a REST Operation. Let’s repeat the steps for running workflow by clicking on Workflows and then write invoke a rest operation in the search box and click run on the second workflow. 

For simplicity we will select the get_findPetsByStatus operation. This operation will allow us to fetch all the pets filtered from one of those 3 statuses – available, pending and sold.

We’ll set our status parameter to available and run the workflow.

We should have successfully ran the workflow. As you see in the logs there is a content as string. This is our response from running the REST Operation.

This scenario can be reused/modified based on the customer needs. We just wanted to demonstrate how extendable the REST Plug-in and vRealize Orchestrator are.

Where to go next

The HTTP Rest plug-in is really powerful plug-in and you can explore more what capabilities in the official documentation.