Tips for Working With the FME Server REST API in FME Workbench

Introduction

APIs are a communication medium that allows us to talk to an application. If you’ve never worked with an API before, I recommend you check out the tutorial series Getting Started with APIs.

In this article, you will find our REST API documentation and some useful transformers that you may consider including in your workspace when working with the FME Server REST API.

Finding the Documentation

The FME Server REST API Homepage is an essential tool for any API user. This website provides the documentation needed to learn about the FME Server REST API. It also allows the user to view all calls available on the REST API. Each call has detailed documentation about the call and any parameters connected to the call. It also allows the user to practice a call before implementing it.

To find this, go to http://<yourServerHost>/fmerest/ replacing <yourServerHost> with your server hostname. 

Once on that page click on the API link.


Here, you can explore the various calls you can make to FME Server. Find the third category called health check and expand the call. You should see this documentation.

This page outlines everything you need to know about the call. Click "Try it out!", this connects to your server and will provide a response to your call. However, before you receive a response you will have to connect to your server.

You will be prompted for the server username and password. This is where you will have to request a token to complete your call.

Next, click Get Token. Now, you should see the token in the top right-hand corner of the page. Once you click "Try it out!" the call can now be made.

After you have made a call to FME Server, you will receive a response from FME Server.

Transformers

HTTPCaller

In FME Workbench the HTTPCaller is your best friend when it comes to working with any API. In this transformer, you’ll configure the Request, any headers or query string parameters and authentication. Depending on the type of request there is an option to specify the upload body as well. Be sure to consult the FME Server REST API Documentation, this includes details of the configuration required for each endpoint. 


HTTPCaller configured with FME Server Rest API
 

JSON Transformers

The majority of FME Server REST API calls return their response as JSON. Therefore to work with the job statistics in FME the JSON string must first be parsed and broken out into attributes. The JSONFragmenter, JSONFlattener and JSONExtractor can be used to perform this action. The tutorial Getting Started with JSON provides an overview of reading, writing, and transforming JSON data using FME.


Parse FME Server Rest API response out into attributes
 

HTMLReportGenerator

To work with Dashboards in FME Server the output must be written to HTML. The HTMLReportGenerator can help you quickly create basic charts in HTML. For more complex dashboards you’ll have to create your own custom HTML. There are online HTML preview tools that can be used to help you put this together. 

HTMLReportGenerator in FME Workbench and HTML Output
 

API Pagination

Most APIs have a maximum number of entries they can return in a single request, therefore to retrieve all the results you need to be able to page data. Usually, this can be done by setting two additional query strings in your request, an offset, and a limit. Offset-based pagination allows you to set the number of records to skip before retrieving your results. For example when Offset=0 and Limit=1000 the response will hold the first 1000 features when the Offset=1000 the response will essentially be returning the second page, the second set of 1000 features, and so on. 

In FME there are two different routes you can take to setting up pagination. If you know the total number of pages you can use the Cloner transformer to create a feature for every offset needed and then feed this into the HTTPCaller. Alternatively, create a custom transformer to make use of looping functionality to continually increase the offset after each request. 

Check out the APIPagination.fmw for examples of both these methods with the GET /fmerest/v3/transformations/jobs/completed endpoint. If your FME Server hasn’t yet reached 1000 jobs, try reducing the limit to see this pagination in action. The webinar To Loop or Not to Loop showcases examples of when looping is appropriate and the best practices in looping, such as Looping Until a Condition is Met. 

Additional Resources

Monitoring FME Server Job Activity using the REST API
FME Server Troubleshooting: REST API