Making a GET Request with HTTPCaller

Introduction

This example demonstrates a basic HTTP GET request to the Bootprint API using the HTTPCaller in FME Workbench. We will then parse the API’s JSON response and send an email with its content. The end result is a workspace that uses an API to send a random fact about the Earth to a recipient of your choice.

Step-by-Step Instructions

1. Create a Workspace

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

• Transformers can be added to the canvas in multiple ways

  Click anywhere on the blank canvas and start typing the transformer name to access the quick add menu
  Click on the Transformer button on the toolbar
  On the top menu bar, click Build > Transformers > Add Transformer.
  Click on the green + on the canvas and select Transformer

  Add an HTTPCaller to the canvas and double-click on it to open the parameters or click the cog icon in the mini toolbar.

  

• Because 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 enables us to initiate a workflow by creating new features that can be processed later in the workspace. Add the Creator transformer by clicking anywhere on the canvas and typing “Creator”.

  

  Add an HTTPCaller and connect your Creator to the input port of the transformer. Double-click on the HTTPCaller to open the parameters

  

As of FME 2025.2, many transformers have been updated to not require input from the creator transformer. For a list of all the transformers with this improvement, please see Transformers with an Optional Input Port

Open the HTTPCaller and take a look around. Note that there are two required fields: Request URL and HTTP method. We will need at least those two pieces of information to make a call. There are many other parameters we can optionally fill out. For now, select Cancel to leave the parameters empty.

2. Review the API Documentation and form the Request URL

Before we can fill out the HTTPCaller parameters, we should consult the API’s documentation. For this example, we will use the Bootprint API. This is a simple API designed to do one thing: send facts about space. 

When choosing an API, always review the Terms and Conditions to ensure it fits your needs. Navigate to the Random Fact heading on the Endpoints page.

The endpoint for random facts here is /fact, with a base URL of:

https://api.bootprint.space/fact

Since we would like Earth facts, we'll use the following request URL:

https://api.bootprint.space/fact/earth

This is a GET endpoint. Opening the above in a browser will display the JSON returned by the API call:

If you are new to working with JSON, see the Getting Started with JSON tutorial to learn more about working with JSON in FME.

3. Start Building the API Call

Our goal is to retrieve a fact about the Earth from the API and bring it into the workspace. With this in mind, we can start building our API call. Return to the workspace and open the HTTPCaller parameters. 

In the Request URL, enter the base URL that you have just constructed.

https://api.bootprint.space/fact/earth

Set the HTTP method to GET, as this is the method specified in the API documentation. GET requests are usually used to retrieve data.

You have the option to write the API response to an Attribute or File. For this example, we’d like to save the response body to an Attribute _response_body so that we can use it downstream. 

Though the HTTPCaller offers many other optional parameters, we only need to modify the Request URL and HTTP method for this request. 

Note that the Bootprint does not require authentication, so we do not need to select the Use Authentication parameter. However, many other APIs typically require some type of authentication for access.

Select OK. 

4. Test the API Call

Turn on Data Caching and select Run. 

Examine the output by selecting the "Looking Glass" icon on the HTTPCaller transformer. A successful translation returns a 200 value to the _http_status_code attribute. This means that the request was received OK and the message has been fetched from the API server. There are many response codes you may receive; it is good practice to familiarize yourself with them. 

http://fme.ly/SpaceFact

5. Examine the API Response

From the table, we can double-click the _response_body attribute to inspect what the API has returned. Use Syntax Highlighting to make the JSON easier to read.

6. Parse the JSON Body

From the JSON shown above, we can see that the "fact" attribute needs to be extracted.

Add a JSONFlattener and connect it to the HTTPCaller. Set the JSON Document to _response_body and the Attributes to Expose to fact.

Hit Run, and ensure the fact attribute has been created correctly.

7. Configure the Emailer

Finally, we can use our workflow to send our randomly selected Earth fact to the recipient of our choice. Add an Emailer and connect it to the JSONFlattener. Open its parameters.

This transformer requires a Gmail/Microsoft Web Connection, or SMTP configuration to work. Enter your Service or SMTP details and continue. 

For testing, set both the From and To parameters to your email. Add a Subject line, like “Earth Facts”, and select the fact attribute as the body. 

Select OK. Your final workspace should look like this: 

8. Check your Email

Run the workspace. Check the inbox of the recipient's email address. Inside, you should find a new email with the subject “Earth Fact!” sent from your workspace. 

Every time the workspace runs, the HTTPCaller makes a GET request to the Bootprint API and receives the most recent data. To get the most out of this workspace, think about setting it up on an FME Flow Schedule to make a daily API call and deliver a random fact to your (or your friend's) inbox.

More on HTTPCaller

This step-by-step guide showed you how to make a simple API call using HTTPCaller and interpret its response. The HTTPCaller has built-in parameters to handle even your most complex API calls from inside FME Workbench. Try another tutorial to get more experience using this transformer in your workflows, or learn more about APIs by reading the Getting Started with APIs tutorial. 

Data Attribution 

Data shown in screenshots comes from the Bootprint API, available under the MIT License.