Tutorial: Configuring the OpenAPICaller

Introduction

This tutorial will use the OpenAPICaller with the National Weather Service OpenAPI, specifically focusing on the OpenAPICaller transformer and configuring the JSON response. To finish off, we will create an HTML report of weather alerts of varying severity.

The OpenAPICaller transformer can be configured with either a file from your local drive or the URL of the OpenAPI (https://api.weather.gov/openapi.json). If the website is unavailable, a copy of the .json file is available on the sidebar. Additionally, referencing the API Documentation will provide insight into any abbreviations used and the endpoints.

The HTTPCaller is a more general-purpose transformer for making API requests but requires users to construct request URLs, set headers, and parse responses manually. In contrast, the OpenAPICaller reads the API definition from an OpenAPI spec and preconfigures the request structure, making it significantly easier to use when working with compatible APIs.

After step 7, the OpenAPICaller's configuration is completed. The remaining steps discuss organizing and filtering the specific results.

Requirements

FME Form 2024.1 or greater is required to access the OpenAPICaller transformer.

Step-by-step Instructions

1. Open FME Workbench and Create a Blank Workspace

In a blank workspace, add a Creator transformer to the canvas. To add a transformer to the canvas, click the highlighted button in the menu bar or type the name directly on the canvas.

The Creator parameters can be left as default.

2. Add OpenAPICaller Transformer and Configure

Add an OpenAPICaller to the canvas. Connect the Creator's Created output port to the OpenAPICaller's Input port. Open the OpenAPICaller's properties by double-clicking on the transformer or selecting the cog icon from the mini menu.

In the OpenAPICaller Parameters, click the Select button to import the API.

In the Import from OpenAPI Specification dialog, paste the National Weather Service OpenAPI URL <https://api.weather.gov/openapi.json>.

If you have downloaded the API, you can click the ellipsis and navigate to the API location on your local drive.

Once the API has been selected, the Import Status pane will populate with information about it, including whether the import was successful, version information, and any issues.

3. Select the Endpoint to Call
The Endpoints available to call will be imported; you can click the down arrow to get the exact endpoint you want. For more information about the endpoints, refer to the API Documentation.

We are interested in active alerts for a given US state. Expand /alerts (4), then expand /alerts/active (5), then finally expand /alerts/active/area/{area} (1) and select GET.

Once an endpoint is selected, the Imported Specification for Selected Endpoint pane will populate with the description, method, base URL, authentication information, and any required path variables. For this call, the only path variable needed is the State.

Once the endpoint is selected, click Import Request Parameters to return to the OpenAPICaller Parameters window.

4. Set Path Variable

If the API you access requires authentication, you can set the authentication type next. The National Weather Service API does not require authentication; we will skip this step. For more information on Authentication in the OpenAPICaller, see the documentation.

The Host URL contains information from the imported OpenAPI in the URL by Parameters section. Next, we need to fill in the Path Variables required in the URL to access the chosen endpoint—in this example, weather alerts for a specific state. The Name is already populated with the area from the endpoint specification; only the Value needs to be populated. The API uses the 2-letter state abbreviations.

Next, we will fill in the Value for the area path variable. Feel free to pick any state for this step, but we will use CA for the remainder of the tutorial.

5. Inspect the Request Preview and Send a Test Request

Now, we will look at the Request Preview in the OpenAPICaller parameters. You may need to scroll. Here, we can see the selected method, the full URL with path variables, and the version. Click Send Test Request to see if the call works and what response we will get.

\

Click Send Test Request, and the Test Response Preview will populate with a response. If there is an error, the response will indicate as such.

If errors exist, read through the response to troubleshoot a possible cause. In the example above, the state value was incorrectly input as CAAA. Click OK to return to the OpenAPICaller Parameters window.

6. Output Configuration and Response Handling

Under the next heading of Output Configuration, we can choose where the response goes and whether to fragment the JSON response as features.

Outputting the fragments as features lets us customize the response and create the JSON query within this one transformer. This differs from the HTTPCaller, where you would need additional JSON transformers after the HTTPCaller to do this work.

For this example, set the Response Handling Mode to Output JSON Fragments as Features, and the JSON query to Fragment as:

json["features"][*]["properties"]

To get other information in the response, click the ellipsis next to the query box to bring up the JSON tree.

Leave the rest of the parameters as default for this tutorial. For more information on the advanced settings, see the OpenAPICaller Documentation.

Click OK to close the OpenAPICaller parameters.

7. Run the Workspace and Inspect the Results in the Visual Preview

Click the drop-down arrow next to the Run button in the menu bar and make sure “Enable Feature Cache” is selected.

Once feature caching is enabled, click the Run button. After the workspace runs, click on the OpenAPICaller Output feature cache to view the results in the Visual Preview window.

In Visual Preview, we can see the API's returned results. The number of rows will change depending on how many alerts are active for a given state on a given date. Click the ellipsis in the _resoponse_body field to open a window showing the entire response.

The response will look messy and hard to read. To see the JSON structure more efficiently, click the ABCXYZ button at the bottom left and choose JSON.

After you have inspected the response, click Close.

This is the end of the OpenAPICaller configuration. The following steps talk about managing the attributes and formatting the data for a report. 

Optional Steps

8. Add an AttributeExposer to Access Additional Attributes within Each Alert

Within each alert's response body, there is more nested information that we could not access with the JSON query. We can access these additional attributes through the AttributeExposer transformer.

Add an AttributeExposer transformer, connect it to the Output port of the OpenAPICaller, and open the parameters. In the table under the Attribute column, select the first row and click the ellipsis to open a window where you can select additional attributes. If you do not see the ellipsis, close the AttributeExposer and run the workspace with feature caching.

Set the following Attributes and Type, and then click OK.

9. Add an AttributeManager Transformer to Keep, Sort, and Rename Attributes

The AttributeManager combines the functionality of multiple transformers and allows you to sort, rename, remove, and update the value or type of individual attributes.

Add an AttributeManager and connect it to the AttributeExposer. Double-click the transformer to open the parameters dialog, scroll to find the attributes exposed from the previous step, and move them to the top of the list by using the ^ button at the bottom of the window.

• Severity
• Event
• Description
• areaDesc
• Updated
• Effective
• ends

Additionally, you can rename the Output Attribute if the original name is not clear.

Finally, select all the remaining attributes and click the - button at the bottom of the window to remove them from the remaining workflow. This helps reduce the amount of data passed from transformer to transformer.

10. Add a TestFilter

The TestFilter creates conditions based on attribute values to pass features to different output ports. In our example here, we can create filters for different levels of severity of alerts - severe, moderate, or minor. For simplicity, only one filter will be created for severe alerts, and all other levels will route to the <Unfiltered> output port.

Add a TestFilter and connect it to the AttributeKeeper.

Double-click the parameters' first row in the Test column to open the Test Conditions dialog. In the Test Conditions dialog, click the drop-down arrow in the Left Value field and select "severity".

Set the Operator to = and the Right Value to Severe to finish the test clause. Finally, the Output Port to SevereAlerts.When multiple test clauses exist, giving each output port a descriptive name is important.

The = operator means the test clause is looking for an exact match of the right value, and it is case-sensitive. If you are unsure of the case or if the JSON response is not standardized, change the Comparison Mode to Case Insensitive.

Click OK to return to the TestFilter parameters. If there were additional conditions to add, you would double-click the second box in the test column “Else If” and repeat the steps above with the other filters.

Click OK to finish configuring the TestFilter. The transformer will update to include additional output ports based on the test conditions that were input.

Run the workspace now and inspect if the TestFilter correctly filters the alerts.

A filter result of 0 can be valid if there are no severe weather alerts for your chosen state on a given day. Inspect the <Unfiltered> results in the Visual Preview to check if this is correct. If severe alerts are in the Unfiltered results, confirm the spelling and case in the TestFilter.

11. Set up an HTMLReportGenerator to Display Alerts in a Table

Add an HTMLReportGenerator transformer, connect it to the TestFilter, and open the parameters.

Here, we can create and customize an HTML report without knowing any HTML code.

First, set the Page Title (a) to Severe Weather Alerts in California. Next, in the Page Contents pane on the left (b), click the Chart (bar) to open all the chart options and select Table. After selecting Table, click on the Content Settings section to update the Table parameters. Under Column Contents (c), click the first row and add each attribute we kept from the previous step. In the Column Name field, you can give each attribute a name that will appear in the final report.

The Preview in Browser button will show an empty table with the page title and columns in the order they appear in this list. No data will be shown. This step just creates the report template. Next, a writer is needed to make an output file.

12. Create an HTML Writer to Create the Final Report

Click on the add writer button in the menu bar.

In the Add Writer dialog, set the e Format to HTML, and the Dataset field will contain the location where the file will be written. Once you select the file location and name in the dataset field, click OK, and an HTML writer will be created on the canvas.

Connect the HTML writer feature type to the output port of the HTMLReportGenerator.

Your canvas should look something like the image below.

Run the workspace and check the translation log to see if any errors occurred. If none are found, single-click on the HTML writer and then click the file icon in the mini menu to open the folder where the HTML report was saved.

Open the HTML report in an internet browser to see your results.

Additional Resources

Getting Started with the OpenAPICaller

Tutorial: Getting Started with APIs

Transforming JSON using the JSONExtractor, JSONFlattener, and JSONFragmenter

Data Attribution

The data used here originates from open data made available by NWS/NOAA.