Integrating APIs into FileMaker apps
In “Data API: breaking down barriers and creating new business models” webinar and in our upcoming FileMaker 2019 DEVCON session you will find multiple examples of powerful API integrations. One of which, the Books sample file, serves as great introduction to integrating REST APIs into FileMaker apps.
Originally, the Books app required that users manually enter each book into the app. That process became cumbersome and even more difficult on an iPhone. In an ideal world, the user could scan a barcode and book information would be entered automatically. However, this strategy requires finding a source that has as much book data as possible.
Some online research led to Google Books, billed as “the world’s most comprehensive index of full-text books”. Combining the power of FileMaker’s database capabilities with Google’s ubiquitous data source would leverage the best parts of each system.
But, getting their data into the app is the trick.
Luckily, Google provides access to their book data through the Google Books API (Application Programming Interface).
Specifically, an API allows other applications to make requests for data. Any data source that provides an API also offers documentation that details how to make these requests and receive the data you are looking for.
The documentation will provide details on how to construct a URL to request the data. The Google Books API, for example, uses the following URL structure to request book data via the API:
https://www.googleapis.com/books/v1/volumes?q=isbn:006091307X
This url actually consists of three distinct sections. Moving from left to right theses sections are the host, the API route, the API endpoint and our query parameter.
Breaking the url into sections we would find this:
The most important part of this example is that the URL specifies a parameter of “q=isbn:006091307X”. This parameter tells Google to return only the Books in it’s database whose ISBN matches 006091307X. This is a piece of data that can be captured in the app and thus, fed to the URL so it can request whatever book we need.
So, now the data source has been identified and the specific URL format required to make a request is also available. Yet, how do we get the data?
The entire internet runs on URL requests and responses. When you do a search on Google, you are really just composing a URL with your search value appended and Google servers respond with data to display your results.
When you use a URL to requests data from an API, you get back data in a specific format. This format is called JSON.
JSON
JSON (Javascript Object Notation) is a widely used data exchange format. JSON consists of key / value pairs grouped together into objects to describe data. A JSON object is a set of key value pairs enclosed within curly braces. Each set of name value pairs are separated by a comma. An object is most equivalent to a FileMaker record.
Specifically, this is an example of the JSON you would get back if you sent this exact URL request:
https://www.googleapis.com/books/v1/volumes?q=isbn:159420411X
The responding JSON document contains every bit of information that Google stores on this specific ISBN number. All the data is formatted in consisten JSON format.
Included in the JSON (see line 3) is an object that has a “totalItems” key with the value of 1. The “totalItems” =1 tells us that the Google Books API found 1 matching book in their database.
Also included in the JSON is an “items” key with a nested object (in an array) containing book data. Later, we will explore how FileMaker can natively parse this data using new calculation functions.
But first, how do we make a URL request in our FileMaker app?
Making the request in FileMaker
(download the Books sample file here)
To make a request to the Books API you can use the Insert From URL script step. The Insert From URL script step also allows FileMaker developers to set a variable with the results of the query. By setting a variable with the response to the query this eliminates the need to store our data in a record before manipulating it.
Saving the data directly to a variable eliminates the need to easily make multiple requests within one script without needing to create additional records or overwrite a specific field’s data.
If you look at the script in the example file called “Add New Book From ISBN Scan — FM16”, you will see that in line 16 there is an “Insert From URL” script step used to initiate the request for the JSON data from the Google Books API that uses the data found in the field called “Books::ISBN” that had previously been captured via a barcode scan.
You will also see that the “target” value used in this script step is the $$json variable. So the returning JSON is stored in the session memory for use later in the script.
Parsing JSON data into fields
With the release of FileMaker 16 developers are now able to use native FileMaker functions to integrate with other services. FileMaker has provided the new function JSONGetElement to work with JSON. JSONGetElement will query json data for a element specified by an object key or path.
In our example, you can use JSONGetElement to parse the book data from the Insert From URL set the $json variable to access your book data (line 18):
To retrieve the name of your book from the object now stored in the $json variable, you could then do this:
Similarly you can access author data by using JSONGetElement to query a nested object in an array.
Once you have selected the data you need using JSONGetElement it is just a matter of setting this data to the appropriate field using the Set Field script step.
You will notice several script steps in the example file starting at script line 38 and continuing through script line 43. You would repeat these steps for every field that you want to contain data from returned JSON.
As you can see in the Books example, pulling data into your FileMaker app from a third-party data source is much easier in FileMaker 16 and beyond.
If you have data that you want to integrate into your own FileMaker app, all you need to do is:
- Find the data source that has an API
- Determine the URL structure required to make a request
- Create an “Insert from URL” call to the API
- Store returning JSON
- Use JSONGetElement in a Set Field script step each time you want to extract data from that URL into one of the field in your FileMaker app.
The new additions to the Insert From URL script step and FileMaker 16’s powerful new native functions for working with JSON data, give FileMaker developers a suite of tools to integrate with other systems allowing developers to interact with a variety of APIs and greatly increase the value FileMaker systems provide to end users.
For more information on FileMaker and APIs, please visit: http://filemakerandapis.com
..where you will find:
- Additional video examples of FileMaker apps integrating data from third party APIs
- Schedule of upcoming live FileMaker and API live events
- Download link of the Books example file referenced in this article
If you need API integration mentoring assistance or if you would like iSolutions to build API integrations into your apps, please visit us here.
