FileMaker Server 16: FileMaker Data API

In FileMaker Server 16, under Web Publishing, you will find a brand-new entry called FileMaker Data API.

Its description explains that web services can use it to access FileMaker data. The truth is – it’s even better than that. It’s open to any kind of integration, not just web services. Any application or system that can make an HTTP call and works with received JSON data in response can use FileMaker Data API. It’s a very powerful and welcome addition to the FileMaker product line. It essentially turns your FileMaker app into a web service.

How to Use FileMaker Data API 

You can reach the web service (your FileMaker app) through a URL endpoint that looks something like this: https://{{server}}/fmi/rest/api/record/the_UI/FRUIT_utility/1 (We’ll explain the structure of this URL later.)

Then use one of the HTTP methods (verbs) to indicate what your desired action is (GET to retrieve data, POST to create records, PUT to update records, DELETE to delete).

The next part of the request is one or more headers. The most common header here is the authentication token to prove that you are an authorized user.

And finally, a JSON-formatted body contains the data you want to send to your FileMaker app. The web service then replies with a response in the JSON format.

Online help for FileMaker Data API is available on the machine where FileMaker Server is installed, at the URL shown below. This detailed documentation provides good examples of what to send and what you receive in return.

https://{{server}}/fmi/rest/apidoc/

Example 1: Authentication

Let’s get practical. For this post, I’ve created a collection of Postman test requests. Postman is a free testing tool our development team uses quite often. It allows you to construct API calls and see what you get back from the web service.

The Postman test requests have been saved as a “Postman collection,” which you can download below. You can import this Postman collection once you have the tool installed. Each test demonstrates the various actions that the FileMaker Data API allows.

https://{{server}}/fmi/rest/apidoc/

Download the Demo Files

In addition to the Postman collection, we’ve created two FileMaker files we used for these tests: the UI and the Data. Both have been enabled for the new FileMaker Data API.

• Download the files (includes the Postman collection, FileMaker UI, and the Data)
• Login credentials (these are included in the Post tests):
  • Account Name: rest
  • Password: rest

Test Requests in FileMaker Data API

Let’s look at three of the test requests and see how they work. First, you need to do is authenticate, i.e., log in.  You then receive a token allowing you to interact with the data. The token is valid for 15 minutes after your last request. It needs to be added as a header to each HTTP request.

The documentation shows that we need to use this endpoint (URL) syntax and that it requires the HTTP POST method.

All requests to the FileMaker Data API will use ‘/fmi/rest/api/”.  Next, the API calls on ‘auth’ for logins and logouts, ‘record’ for all data manipulations, ‘find’ for searches, and ‘global’ for setting global fields.

Wherever the API documentation mentions ‘:solution’, use the name of the FileMaker file you want to target.  Use just the file name, no leading ‘:’, no ‘.fmp12’ extension.

Where the API documentation uses ‘:layout’, just use the target layout name, sans the ‘:’. Using web compatible files and layout names makes your life much easier. Don’t forget to avoid spaces and special characters.

In our Postman request, we used this process, with the name of the FileMaker file (“the UI”) that we want to work with.

In Postman, the “{{server}}” is a placeholder set in the Postman ‘environment’ section. I can easily change servers without having to update each individual request. I use a similar placeholder for the token once we have it.

That takes care of the endpoint. The documentation also tells us what headers we must specify for the request: ‘Content-Type’ is required, and the ‘X-FM-Data-Login-Type’ is only needed if we want to use OAuth to log in.

We are going to use a normal FileMaker account to log in, so we’ll skip that optional header and just set the content type:

The last thing we need to do is to set the body. The documentation explains what needs to go into the body. It also provides an example of what the whole thing should look like:

Then use Postman to construct the piece of JSON to send over. In that JSON, we add the username and the password to use for the login, but we also need to add the name of a layout.  The layout is a bit of an odd duck in this request; it can obviously be the layout that you will want to use for the actual data interaction, but at a minimum, the provided user credentials must have access to that specified layout or the authentication will fail. Here’s our request in Postman:

We are now ready to send this request over to FileMaker. When we have everything right, we will get a JSON response that contains the token:

If the login fails, the return response would be:

After a successful login, you can copy the token to the {{token}} environment placeholder. This makes it available to all subsequent requests.

Example 2: Retrieve Data

Now that we have a valid token let’s use it to retrieve some data. In fact, let’s ask for all 10,000 records in the FRUIT table. We will use the ‘FRUIT_utility’ layout for this, as shown in the screenshot below. It has a nice mix of different field types on it:

As per the documentation, we need to create a GET request, specifying the FileMaker file (:solution) and the target layout (:layout). We need to specify the token in the header.

In Postman, it looks like what’s shown below, where ‘the_UI’ is the file and ‘FRUIT_utility’ is the layout:

When we send the request, we receive a response with the FileMaker data in JSON format:

You might expect this to contain the data for all 10,000 records, but that is not the case. The Data API limits the returned found set to 100 by default.

Note that Postman also gives us feedback on the time it took for the Data API to respond and the size of the response: 78 milliseconds for 100 records.

If we really want all 10,000 records, we can modify the request to add the ‘range’ keyword and set it to the exact number of records. Or, if we are not sure of how many records there are, we can use a very large number.

As you can see, it now took just over a second and a half to get all 10,000 records. The total response size is just over 7MB.

One thing we should note about JSON data we receive from FileMaker: all data is returned as JSON text (everything is quoted), even numbers and dates. The system receiving the JSON will need to factor this in.

The test requests in the Postman collection will demonstrate some of the nuances in the JSON syntax for things like portal data if you have an object name set for your portal, what repeating fields look like, and other variations.

Example 3: Modify Data

The last example shows the endpoint structure — headers and body to use when we want to edit a specific record. In this example, we want to change the value of the ‘fruit’ field on the record with record id 10007.

As per the documentation, we’ll need to use the PUT HTTP method, set two headers, and use a JSON body that includes the field that we want to update and the new value. The URL has to include the FileMaker file name (:solution), layout (:layout), and the record’s id (:recordId).

This raises a question: what do we use for the record id, and how do we know the value of the record id?  ‘recordId’ is the internal id that FileMaker assigns to every record. It is not your own primary key or serial number. For the purpose of this demo, I have created a field in the FRUIT table that shows us the record id, so that we can actually see it on the layout:

Even if you do not have such a field, the record id is always part of the JSON that the Data API returns if you create a record or search for records. If you do a search through the Data API and then process that response, you will have the record id you need:

Back in Postman, our request looks like this with the URL (ending with the record id) and the headers:

In the body, we have some JSON that contains the name of the field that we want to update:

When the request is sent, the Data API response indicates all is well:

Or, if we messed up and specified a field name that does not exist, we will get this back:

These examples are basic. The JSON payload (body) gets more complex when you do searches and other requests, but I hope this introduction was helpful to get you going with the new FileMaker Data API.

How does FileMaker Data API stack up against other APIs?

We still have the traditional APIs at our disposal (ODBC/JDBC, XML, and PHP). The most straightforward comparison is with the XML API. They both work off request URLs, they return data in a particular format, and they do not require any drivers or other setup like ODBC does, for example.

The Postman collection includes one XML test that also asks for all 10,000 records from the same table, through the same layout. In our testing, we have found the Data API to be consistently faster than the XML API. Below is a screenshot showing that it took over 3 seconds to retrieve the data through the XML API. The Data API took just over 1.6 seconds.

The Future with FileMaker Data API

On the FileMaker Server admin console, it states that the Data API is a trial that expires at the end of September next year (2018). Given that FileMaker Inc. releases a new version every year around May, we expect the Data API to be officially released with FileMaker 17 well before this trial expires.

We do expect that at some point, the support for the XML and PHP APIs will be deprecated and that all development focus will go to this new FileMaker Data API. Keep an eye on the FileMaker roadmap for this.

Even when they eventually get marked as deprecated, XML and PHP APIs will clearly be around for a long time. There’s no need to rework any existing integrations you have that use those APIs. However, consider the new Data API for any new and upcoming work

There are definitely some downsides to the Data API. It does not have the ability to execute scripts, a capability both XML and PHP APIs boast. It also requires using the internal record id of a record to identify the record.  That record id is not as set in stone as it needs to be to permanently point to the same record.  For example, if you delete the record from the FileMaker file and re-import the same record from a backup, the record id will be different. Your primary key will still be the same, but the internal record id will change. Any REST url pointing to this record through its original record id will break.

Our FileMaker Data API Recommendation:

Get familiar with this new feature. It is an exciting and promising addition to FileMaker developers’ integration arsenal. However, be careful when committing to it for production projects. The API will likely undergo tweaks before its official release. The licensing pricing model is unknown at this point too.

Moving Forward with FileMaker 16

If you have any questions about how to leverage the FileMaker Data API or any other new features included in FileMaker 16, please contact our team. We’re happy to help your team determine the best way to leverage them within your FileMaker solution.