| Exercise | Calling an API within FME |
| Overall Goal | To show how to call a Web API within FME |
| Demonstrates | How to use the HTTP Caller to make a simple web request and view the Results |
| Completed Workspace | Download |
This exercise is a basic introduction into how you can make a simple call to a web service within FME and what the results look like.
We will build a simple workspace that makes a request to the Dublin Bikes API to retrieve information on the station locations including the number of bikes available. The initial part of the workflow makes a simple request that returns all stations along with the associated metadata for the latest point in time. We will then build up our request to get specific station information in a given time period.
1) Create a New Blank Workspace
Open FME Desktop and select New to create a new blank canvas.
2) Add transformers
Add a Creator transformer to act as a trigger for the workspace.
Add a HTTPCaller transformer, and connect this to the Creator transformer.
3) Configure the HTTP Caller
The workflow to make the request to a web service is quite simple, but the bulk of the logic is typically contained within the HTTPCaller. In this next step we will configure the transformer to make the request.
The initial step is to set the URL we will be calling. Open the transformer and set the Request URL to the following location.
https://data.smartdublin.ie/dublinbikes-api/last_snapshot/
The transformer should like this once set,
As this request is just a call to the web service for data it is made using the GET method, so set the transformers HTTP Method to GET.
4) Run the Transformer and Review
Using the Run to capabilities in FME run the HTTPCaller to make the web request.
Note: If you do not see the Green Triangles pop up when you hover over the transformers Run with Feature Caching may not be enabled. To turn this on go to the Run Menu and ensure that Run with Feature Caching is enabled.
After the workspace has run, the green inspection icon on the Output board should show up. This allows us to quickly inspect the response from the web service.
Clicking on the Output port inspection icon should open the output in the Visual Preview window, and show the following fields. The http status code attribute value should be 200 with indicates a successful request was made to the service. The response its self will be contained within the response body attribute.
Note: If you do not see the Visual Preview panel you can toggle it on by going to the View menu, then Windows and selecting Visual Preview to enable it.
Selecting the response body attribute will open up the response in a larger window so that it can be reviewed. You should be able to see the JSON content from the service including the different stations and the other attributes returned by the service for each station.
Currently this data is a jumble and quite hard to read but we can use the JSON transformers within FME to work with the response so that we can turn it into a more traditional set of features with attributes and geometry.
Note: FME supports syntax highlighting for JSON within the text panel, you can toggle this on by selecting it from the ABCXYZ menu icon at the bottom left of the panel and choosing JSON.
5) Using Query String Parameters
The above provides a simple example of how we can query an API and get a response from the web service, but typically when calling an API we would want to pass a number of parameters into the service.
The Dublin Bikes API stores historical information on the availability of bikes at each location and we can use the API to query a given time period for any station within the network. We will call the same service as before but this time we will use the historical method rather than the lastsnapshot method.
The URL we will call is:
https://data.smartdublin.ie/dublinbikes-api/historical/
and we will use the following query string parameters.
| parameter | value |
|---|---|
| init | 2021-04-13 17:00:00 |
6) Attributes as Parameters
In order to make the workspace easier to maintain and also to demonstrate how we can use attribute values within the HTTPCaller we will create attributes to pass the query string parameters in. This has the advantage of making the workspace more flexible and allowing multiple requests to be made depending on the attribute values.
We could for example use the same transformer to make a request for different time periods by having a series of features each with the temporal epoch we want to query.
To do this we will add an AttributeManager between the Creator and the HTTPCaller as shown below.
Having added the AttributeManager open its parameter window and add an attribute called _init along with the default value shown in the table above.
The attributes are called the same as the query string parameters but with an underscore added. The underscore prevents FME getting confused when we try to reference the parameter name later. If the name is shared with an Attribute name FME will default to using the attribute name, so when run it will use the attribute value as the parameter name in the web service request.
7) Update URL Called
Having created the attributes we need to apply these in the HTTPCaller, and update the URL to the new method.
Open the HTTPCaller and update the Request URL to the following leaving the HTTP Method as GET.
https://data.smartdublin.ie/dublinbikes-api/historical/
Then expose the Query String Parameters option below this.
8) Set Query String Parameters
In the Query String Parameters section add the parameters for the url call under the Name section and for the Value section select the appropriate attribute for each parameter as shown below.
8) Run the HTTPCaller
Run the HTTPCaller which will make the call to the Web Service, you can also see the call request being made within the log file so you should see the full parameterised call to confirm the request is being made as expected.
Click on the Inspection Port on the HTTPCaller to show the output result in the Visual Preview to confirm the response returned a 200 code.
Click on the Response Body attribute to view the returned data. This will show the number of bikes available at 5 miniature reporting periods between 9am and 10am.
9) Change the Attribute Values
Try changing the values in the AttributeManager and rerunning the HTTPCaller to see the difference in the output result.
For example you can try a year later at the same point in the year to see if there any differences between 2019 and 2024.
| parameter | value |
|---|---|
| init | 2022-04-13 17:00:00 |
| init | 2023-04-13 17:00:00 |
| init | 2024-01-25 17:00:00 |
| CONGRATULATIONS |
By completing this exercise you have learned how to:
|