Getting Started with the OpenAPICaller

Introduction

The OpenAPICaller transformer provides users with an easy way to interact with API endpoints by importing an OpenAPI specification, which can be provided as a JSON or YAML file.

By providing an OpenAPI specification, the transformer will populate a list of available endpoints and automatically populate all the appropriate parameters for the user when an endpoint is selected. This takes the guesswork out of configuring an API endpoint in FME Workbench. 

If users do not have access to an OpenAPI specification, then it is recommended to use the HTTPCaller instead to manually configure an API call.

Requirements

• FME 2024.1 or greater is required to access the OpenAPICaller transformer. 
• Access to a REST API that supports the OpenAPI specification is required for this tutorial and for use in the OpenAPICaller transformer.
  • If you have access to an FME Flow instance, then you can use the FME Flow REST API V4 OpenAPI specification to follow along with this tutorial. To view the FME Flow REST API V4 documentation and gain access to the OpenAPI specification, go to the following URL in your web-browser: https://your-fme-flow-instance/fmeapiv4/docs/index.html 
  • In this tutorial, we will be using the FME Flow REST API V4 OpenAPI specification. The steps may vary slightly depending on your OpenAPI specification. 
  • The FME Flow REST API V4 is currently in Technical Preview. It is under active development and in the stages of being tested.

Step-By-Step Instructions

1. Create a New Workspace

Open FME Workbench and create a new workspace to begin building your workflow on an empty canvas.

2. Add a Creator 

Since we will be getting our data from an API, we don’t need to use a reader for incoming files or connections. The Creator transformer lets us start a workflow by creating new features that we can process later in the workspace. Add the Creator transformer by clicking anywhere on the canvas and typing “Creator”.

3. Add an OpenAPICaller

Next, we can add the OpenAPICaller transformer to our workspace and connect it to the Creator.

4. Import the OpenAPICaller OpenAPI Specification

Open the OpenAPICaller parameters by double-clicking on the transformer.

The first step is to provide the OpenAPI specification and select the endpoint we want to use. 

In the parameters, click on Select to open the Import From OpenAPI Specification dialog.

Click on the ellipsis (...) next to the Specification parameter and open your OpenAPI Specification file. In this example, we will use the FME Flow V4 REST API OpenAPI Specification. If you’re unsure how to locate the FME Flow V4 REST API OpenAPI Specification, please refer to the Requirements section in this article.

Once the OpenAPI Specification has been opened, the Import Status and Endpoints will be updated.

For this example, we will use the GET /jobs endpoint. Under the Select Endpoint section, scroll down to the /jobs group of endpoints, and expand to view the different options. 

Select the GET endpoint and view the information that appears on the right. 

When we click on an endpoint, information is provided on the right based on the OpenAPI Specification. The level of detail will depend on the OpenAPI Specification file itself. 

In this case, the FME Flow REST API specification provides information on the Endpoint Description, Method, Base URL, and descriptions of all the Path Variables, Query Parameters, and Request Headers.

Click on Import Request Parameters. This will close the Select Endpoint dialog and populate all the necessary parameters and fields in the OpenAPICaller Parameters. 

5. Configure the OpenAPICaller Parameters

The FME Flow REST API requires valid authentication to run successfully. In the OpenAPICaller, enable the Authentication parameters.

Set the Authentication method to Web Connection.

For the Web Connection, select an existing FME Flow web connection or click on the Add Web Connection option to create a new FME Flow web connection.

Under Query String Parameters, we need to provide a value for the status parameter; otherwise, the API call will return a failure message. For the Value field, type in success.

6. Send a Test Request

Optionally, you can send a test request ahead of completing the parameter configuration. This will provide you with a preview of the results from running the OpenAPICaller without having to close the parameter window and run the workspace.

Click on Send Test Request. This will open the HTTP Test Request Preview dialog. Click on Send Test Request. Once sent, you will receive a test response which you can view in the preview window.

Click OK to close the Test Request Preview dialog.

7. Output Configuration

The last parameter that needs to be set in the OpenAPICaller Parameters is the Response Handling Mode. You can choose to set this to Save Entire Response body if you want to receive the full response back from the REST API or set it to Output JSON Fragment.

For this example, we will set it to Output JSON Fragment. This mode performs JSON post-processing on the response body, equivalent to the JSONFlattener and JSONFragmenter transformers. The object keys and values contained within the response body will be extracted into FME attributes.

For the JSON Query to Fragment parameter, click the ellipsis to open a dialog containing the JSON structure. Expand items and then click on <array values>. 

Click OK to accept these values. You should see the JSON Query to Fragment parameter change to reflect this selection. Click OK to close the OpenAPICaller parameters.

With feature caching enabled, run the workspace. Inspect the cached features by clicking on the green symbol on the OpenAPICaller Output port. Each feature output from the OpenAPICaller represents a job from your FME Flow instance.

In the Table view in Visual Preview, you can see the _response_body attribute which contains the full JSON response. In the Table view we can also see all the exposed attributes as a result of the JSON Query set in the OpenAPICaller.

For more information on the OpenAPICaller, please refer to the OpenAPICaller documentation.

8. Attribute Cleanup & Exposing Additional Job Information [Optional] 

The JSON query specified in the OpenAPICaller returned useful information to do with each job, however, it also created an array containing information on all the jobs run for each row output. We may want to clean these attributes up a bit before building the rest of our workspace.

To do so, add a BulkAttributeRemover to the workspace and connect it to the OpenAPICaller Output port. 

Open the BulkAttributeRemover parameters. For the Expression to Remove parameter, enter the following:

items{

This will remove all attributes with the “items{“ prefix. Run the workspace and inspect the BulkAttributeRemover output. A bulk of our attributes have been removed, however we still have unexposed attributes present in each row.

To expose these attributes for each row, we can use the AttributeExposer. Add an AttributeExposer to the workspace and connect it to the BulkAttributeRemover Output port. 

Open the AttributeExposer parameters. Click on Import drop-down and click From Feature Cache.

In the dialog, you can select or deselect which attributes you want to expose. We’ll keep the default selection for this example. 

Click Import to import the attributes. Click OK to accept the new parameters.

Run the workspace and inspect the feature cache on the AttributeExposer. In Visual Preview, you can now see all the job information for each job that has run on your FME Flow instance.