Call Public APIs Without Programming

Interest in Business Automation is being accelerated by the thousands of public REST APIs available from countless service providers.

Most are available on a Freemium basis – free low-volume use for development, with a modest monthly fee for production use. The Trisotech Low-Code Business Automation platform lets you incorporate these services in your BPMN models without programming. You just need to configure a connection to them using the model’s Operation Library. With many public APIs, that configuration requires simply importing an OpenAPI file from the service provider. OpenAPI – sometimes called Swagger – is a file format standard for REST APIs. The problem is that most public APIs don’t provide one. Instead they provide documentation that you can use to configure the Operation Library entry yourself. If you’re not a developer, that sounds daunting, but it’s really not that hard. This post will show you how to do it.

A REST API is organized as an interface containing a set of operations. The interface specifies a base address, or server URL, and some means of authorization, such as an API key. Each operation performs a specific function, and is addressed by a path appended to the base address or endpoint. To invoke the operation, a client app sends an http message that contains the required information to a URL concatenating the base address and path. That information includes:

• The http method: POST, GET, PUT, PATCH, or DELETE, indicating whether the operation is reading, writing, modifying, or deleting data.
• The authorization credential
• Input parameters for the operation, required and optional, typically specified as json

Upon receipt of the message, the service is executed and returns some response message, which includes:

• A standard http response code. A code of 200 indicates success, 404 means the base URL was not found, 401 not authorized, 500 either a bad request or internal server error, etc.
• Output values for the operation, separately for each response code, again specified as json

Compared to the earlier generation of SOAP-based web services, REST APIs are simple and standardized. This is their great attraction!

In my Business Automation training, we make use of a real-time stock quote service from Rapidapi.com, a popular aggregator of public APIs. The service we use is called YH Finance, a clone of the old Yahoo Finance API. The documentation page looks like this:

The interface is huge, with operations collected in groups. The one we want is in the group market, with the path /market/v2/get-quotes. Selecting that from the panel on the left, we see the operation documentation in the center panel, which specifies the parameters of the operation, and where in the message they are placed: in the message header, message body, or query portion of the URL. Here two parameters are required in the http message header: X-RapidAPI-Host is the server URL, yh-finance.p.rapidapi.com. X-RapidAPI-Key is the requester’s personal authorization credential. Two more parameters are required in the query: region, enumerated text, and symbols, a comma-delimited string containing stock tickers.

This documentation is all we need to create the input side of the Operation Library entry. Manually add an interface YH Finance and an operation Get Quotes. In the interface properties enter the Server URL and the authorization type. In the operation properties enter the method, path, and under Inputs the required parameters except for the API key, which is assigned to an individual and entered separately when the process containing the service invocation is compiled and published. Clicking the pencil for each input lets you specify its datatype, a FEEL type you must create from the documentation. It’s actually quite easy!

Configuring the operation output is slightly trickier. Notice in the API documentation the button Test Endpoint in the center panel. Clicking that executes the operation with the default parameters shown, in this case a string listing three stocks.

The documentation page then shows the resulting output, as you see here: an outer element quoteResponse with two components, an array of result – one per stock – and error. Expanding result, we see it contains 97 components – wow, that’s quite a lot – of which we only need three: quoteType, bid, and ask. But we do not need to construct a FEEL type with all 97 components. As long as we respect the basic structure, we can omit the 94 result components we don’t need! So we can create FEEL type tTradeQuote, a structure with enclosing element quoteResponse containing a collection of result plus error, and the type of result contains just the three components we need. When the service is invoked, the json response message is mapped automatically to the FEEL tTradeQuote structure.

To incorporate this operation in your Business Automation model, simply click the gear icon on a Service task and bind the task to the Operation Library entry. The service inputs – symbols, region, and x-rapidapi-host – become the task inputs, and the service output quotes becomes the task output. Then, using the Low-Code data mapping explained in a previous post, you just need to map data objects in the process to the task inputs and output. When you Cloud Publish the process, you will need to enter your API key. And that’s it!

So just because your API provider doesn’t offer an OpenAPI file, don’t think it’s inaccessible to Low-Code Business Automation. It’s actually quite easy.