Getting started with the OpenAPI Connector in Boomi Flow
-- Ben DeBoer, Boomi Solutions Architect
Introduction
Have you ever wanted to get info from a public API directly into Flow? With the introduction of the Boomi Flow OpenAPI Connector, now you can!(Disclaimers, etc)
This purpose of this document is to provide some context for, and a simple example of using the Boomi Flow OpenAPI Connector. It is written for non-developers and will not provide a comprehensive review of the Connector, nor will it attempt to address every possible nuance of OpenAPI. As of this writing (early 2022), the OpenAPI Connector in Boomi Flow is in Early Access status. There are likely to be many upcoming changes to this Connector, and it should not be used in a production setting until GA (General Availability) release. To gain access to the complete Early Access documentation and stay informed about new developments, join the Early Access program here: https://community.boomi.com/s/tech-preview.
The Case for OpenAPI as a Flow Connector
If you have used Boomi Flow in the past, you're likely familiar with the concept of Connectors (formerly Services) in Flow. These Connectors are bits of Java code that handle requests from Flow, take action on the request data (possibly transforming it or passing it to another system), and ultimately returning a response to the running Flow. These communications are highly specific to the endpoint being contacted, and any structured data generates Types in Flow that are immutable from the build canvas.
I'm sure we've all seen this one before!
The OpenAPI Connector allows you to define a connection for any RESTful API using a "simple" .yaml file containing the permitted endpoint paths and the structure of requests and responses. "Simple" is in quotes because while this is far simpler than writing your own Flow Connector in Java, the sheer amount of configurable options and number of potential paths and parameters in API calls means the complexity of your .yaml file can grow quite quickly. You can find links to the full OpenAPI specification and APIs-guru (a catalog of OpenAPI documents) in the Resources section at the bottom of this document.
Example Use Case: Get the current comic from xkcd.com
Randall Munroe publishes one of my favorite webcomics: xkcd.com. Mr. Monroe also provides a perfect API to demonstrate configuring the Flow OpenAPI Connector in its simplest possible form. Our example will take the OpenAPI doc published here, and strip it down to a single API call: Get the current comic, and return it as an object in Boomi Flow.
The API: https://xkcd.com/info.0.json
Navigating to https://xkcd.com/info.0.json, we get a JSON response containing information about the current comic displayed on xkcd.com.
API response
Configuration: xkcd.yaml
An extremely simple xkcd.yaml file that enables handling this API call might look like this:
A super-simple configuration file
Note: .yaml files are extremely sensitive to formatting (indents / whitespace / etc ) - a link to this file is available in the Resources section at the bottom of this document.
Some points of interest:
- servers
- defines the location of the API (e.g. http://xkcd.com)
- paths
- defines the endpoints of the API (e.g. /info.0.json, which is used to retrieve current comic info)
- responses
- define different response formats based on the returned http code (e.g. 200 = ok)
- schemas
- define the data structure for requests or responses (think Types) and may contain the Flow Extensions that provide instructions to Flow for how to interact with the data
- x-flow-type: defines the Type to be generated in Flow
- x-flow-query / x-flow-load: These are clues to Flow that the action that uses this schema will be invoking an http GET to return object(s) to the the Flow. Both options are implemented via the Database Load step on the Flow canvas.
- If you are providing query parameters to filter the results ("Get the data based on a 'where' filter") or not filtering the results, x-flow-query will be used.
- If you are selecting the "Get the data based on a unique identifier" filter, x-flow-load will be needed.
- x-flow-save / x-flow-update: These clues indicate Flow will use the Database Save step on the canvas to execute http POSTs and PUTs (respectively)
- x-flow-delete: This clue indicates Flow will use the Database Delete step on the canvas to execute http DELETEs
- Other Flow Extensions are defined in the official documentation
- schemas can be defined once and referenced using the $ref pointer
- define the data structure for requests or responses (think Types) and may contain the Flow Extensions that provide instructions to Flow for how to interact with the data
After the .yaml is configured, it must be hosted somewhere the Flow platform can read it (the Assets folder of the Flow tenant works nicely!)
Configuring the OpenAPI Connector in Flow
We create the Connector in Flow just like any custom Flow Connector, providing flow://openapi as the Connector URL, and a configuration value for the Schema URL. The Schema URL is just a String value containing the publicly-accessible URL for your .yaml file (this example is just pointing to the Assets folder in the Flow tenant)
Note: The other Connector configuration values are relevant to authenticating your API call, which is outside the scope of this document.
If all has gone well, you should have a brand-new Flow Connector! Checking the Types nodes of the build canvas, we can see the "comic" Type we defined in the /components/schemas section of the .yaml file:
Note: "year" is missing on the left side because Flow paginates at 10 properties --- trust me, it's there!
Creating the Flow
With the new Connector and Type in hand, it's now just a matter of using the Database Load step to get the information
Result
That's it! We can now view the current comic by retrieving the path to the image (and some extra metadata) from the API directly from Flow!
(I drew this -- the actual site is much better, I promise)
Click HERE to see a functioning example!
Summary
In this document, we've explored the reasons the Flow OpenAPI Connector is such a needed and welcome addition to Boomi Flow. It allows direct exchange of information with any API reachable from the Flow Runtime, without the need to write custom Java code. We created an simple example Flow that gets the current comic from http://xkcd.com and displays it along with other metadata. This barely scratches the surface of the possibilities OpenAPI opens up to Flow. If you would like to know more about this exciting new feature, consider joining the Early Access program here: https://community.boomi.com/s/tech-preview.
Resources
OpenAPI Specification: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md
APIs-guru: https://github.com/APIs-guru/openapi-directory/tree/main/APIs
Example .yaml file: https://master-boomi-flow-assets-prod-us-east-1.s3.amazonaws.com/9d3001e7-d028-4f85-a032-3525238f5c64/xkcd.yaml
Example Flow: https://flow.boomi.com/9d3001e7-d028-4f85-a032-3525238f5c64/play/default/?flow-id=8f1dae16-7710-4a6d-abce-17ebf9f18619
Example Flow Sharing Token: wJmRkS2Wh5xFPCAm26OcdnJP9MliAsvikoO+u1Hre+nTK91K8+VZadtTfN3UweId