BlogFileMaker

FileMaker Server 16: FileMaker Data API

By May 12, 2017 May 8th, 2019 23 Comments

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

FileMaker Data API

Figure 1. FileMaker Data API under Web Publishing

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/

FileMaker Data API - Get Record

Figure 2. FileMaker Data API – Get Record

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.

FileMaker Data API - Postman Test

Figure 3. FileMaker Data API Postman Test

FileMaker Data API - Test Files

Figure 4. FileMaker Data API – Test Files

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 creditials (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.

FileMaker Data API - HTTPS Post Method

Figure 5. FileMaker Data API – HTTPS 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 file 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.

FileMaker Data API - Postman Request

Figure 6. FileMaker Data API – Postman Request

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.

FileMaker Data API - Manage Environment

Figure 7. FileMaker Data API – Manage Environment

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.

FileMaker Data API - Content Type Specification

Figure 8. FileMaker Data API – Content Type Specification

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:

FileMaker Data API - Content Type

Figure 9. FileMaker Data API – Content Type

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

FileMaker Data API - Body Parameters

Figure 10. FileMaker Data API – Body Parameters


FileMaker Data API - Postman Test - Get Layout

Figure 11. FileMaker Data API – Postman Test – Get Layout

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:

FileMaker Data API - Postman Request

Figure 12. FileMaker Data API – Postman Request

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:

FileMaker Data API - Postman Request

Figure 13. FileMaker Data API – JSON Response

If the login fails, the return response would be:

FileMaker Data API - Login Fail Response

Figure 14. FileMaker Data API – Login Fail Response

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:

FileMaker Data API - FRUIT Utility Layout

Figure 15. FileMaker Data API – FRUIT Utility Layout

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.

FileMaker Data API - Specify Token

Figure 16. FileMaker Data API – Specify Token

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

FileMaker Data API - Specify Token - Postman Test

Figure 17. FileMaker Data API – Specify Token – Postman Test

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

FileMaker Data API - Request Response

Figure 18. FileMaker Data API – Request Response (Click to enlarge.)

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.

FileMaker Data API - Response Status

Figure 19. FileMaker Data API – Response Status

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.

FileMaker Data API - Record Numbers

Figure 20. FileMaker Data API – Record Numbers

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.

FileMaker Data API - JSON Data

Figure 21. FileMaker Data API – JSON Data

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).

FileMaker Data API - PUT HTTP Method

Figure 22. FileMaker Data API – PUT HTTP Method

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:

FileMaker Data API - Record ID

Figure 23. FileMaker Data API – Record ID

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:

FileMaker Data API - Record Search

Figure 24. FileMaker Data API – Record Search

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

FileMaker Data API - Postman Request

Figure 25. FileMaker Data API – Postman Request

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

FileMaker Data API - Body JSON

Figure 26. FileMaker Data API – Body JSON

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

FileMaker Data API - Response

Figure 27. FileMaker Data API – Response

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

FileMaker Data API - Error Response

Figure 28. FileMaker Data API – Error Response

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.

FileMaker Data API - Data Retrieval Time

Figure 29. FileMaker Data API – Data Retrieval Time (Click to enlarge.)

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

We have one caveat: it is unclear at this point if the use of the new FileMaker Data API – once officially released – will require some sort of connection-pack licensing. We will keep our ear to the ground on this.

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 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.

Wim Decorte

Wim Decorte

Wim is a Senior Technical Solution Architect at Soliant. He is a FileMaker 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 and 17 Certified FileMaker Developer and the author of numerous Tech Briefs and articles on FileMaker Server. Wim is one of the very few multiple FileMaker Excellence Award winners and was most recently awarded the FileMaker Community Leader of the Year award at the 2015 FileMaker Developer Conference. He is also a frequent speaker at the FileMaker Developer Conference and at FileMaker Developer groups throughout the world. In addition to being a renowned expert on FileMaker Server, Wim also specializes in integrating FileMaker with other applications and systems. His pet project is the open source fmDotNet connector class that he created.

23 Comments

  • […] Source: How to Use the New FileMaker Data API in FileMaker Server 16 […]

  • Avatar Gianluca says:

    Hi, thanks a lot for this very useful article.
    It works a treat!

    The question that I have is how can I build a Filemaker to Filemaker data exchange with this?
    Let’s say I have a Filemaker Go file that I want to sync with the database shared in FMServer, I could use the GET to retrieve all the records I need and load them into the Filemaker Go file. I was thinking of a text field in the FMGo file that I set with the “Insert from URL” instruction so I can get the data and then split them into a local table.

    Do you think is possible?

    Thanks a lot!
    Gianluca

    • Wim Decorte Wim Decorte says:

      Hi Gianluca,

      Thanks for the feedback. Yes; as a concept that would totally work. Note that ‘insert from URL’ now supports setting a variable directly so you wouldn’t have to store it in a field.

      One thing to keep in mind: when the Data API is released officially it may come with a licensing cost so take that uncertainty into account when defining your strategy.

      Best regards,
      Wim

    • Avatar Erik Wegweiser says:

      Actually, in order to learn the new Data API, for lack of any other technology, I started with a FileMaker file that easily created a record on the server through an API call. Great! But what next? What do I need to do to allow webhooks of a service (like ShipStation) to talk to my database via the Data API? Here, I don’t have the ability to custom specify everything needed to communicate. Where do you start from zero with (I think) Node.js (or what other Data API-compaible technology)?

      • Wim Decorte Wim Decorte says:

        Hi Erik,

        The Data API as such is clearly defined, if you need more functionality to accommodate another service then typically we build a go-between in whatever technology is best for the job and/or fits the chosen technology stack of the client (PHP, Ruby, JS, C#, …). That also offers a nice layer of abstraction so that we switch out the backend without affecting what is exposed to the other service. Where do you start: pick a technology, tinker with it, find a trusted partner that can mentor you, join the forums for that technology.

  • Avatar Hans Erik Hazelhorst says:

    Hi Wim,

    Thank you for this excellent introduction and for taking the time to make this documentation. The data API looks very promising and following this intro is also valuable as a way to get accustomed with webservices in general, PostMan, and oAuth.

    Two questions:
    1. Is there a special reason why you use two fmp12 files for this example? I am a proponent of data-interface separation myself, but other that that, are there security reasons for this choice?

    2. I heard recently that the RestFM solution from Goya Ltd (which uses the PHP API) is preferred by some developers because it has better security and other features. Notably, the ability to run scripts as part of a API call handling. Do you have any ideas on that issues that may help me choose one solution over the other?

    Beste Regards,
    Hans Erik Hazelhorst

    • Wim Decorte Wim Decorte says:

      Hi Hans,

      Thanks for the feedback.
      No special reason for the data separation in this demo, except that I wanted to verify that it works ok for those types of deployments. No security reasons.
      We have used RESTfm in various projects over the years and will continue to evaluate it for the task at hand. One of the major drawbacks of the new Data API clearly is that we can’t run scripts. We can still do it through the XML API if need be while using the new API. For us it is mostly the uncertainty around the Data API licensing model that could prevent us from using it. It’s security is good though so that would not turn us away. RESTfm does offer some more options all around.

  • Avatar Roger Jacques says:

    Thanks for the great summary Wim!
    If I understand correctly, FMI has chosen to use Put for sparse updates, rather than Patch. I wonder what the thinking behind that is, if you happen to know.

  • Avatar Christian Breu says:

    What could be the problem, when using the url of a container field retrieved by a api call to fill a local container field by insert from url and the data in that field is corrupted?
    It looks like the perfect match but seems not to work. When inserting the url in a web browser downloaded file can be opened, when inserting from url, the file gets broken.

    • Wim Decorte Wim Decorte says:

      Hi Christian,

      Go ahead and post the question on community.filemaker.com or fmforums.com. Many of us are on those forums and others can chime in too with ideas and things to try.

      Best regards,
      Wim

  • Avatar rjakesgravatar says:

    Thanks Wim!

    I entered an idea that explains the RFC standards a bit, and why they should be followed.

    A standards compliant implementation of PUT would actually be a great way to “reset” a record, in that leaving a column out of the PUT payload could indicate that you want the auto enters to fire (without regard to the dependency tree.) Either way though, RFC clearly says that sparse updates should be PATCH.

    https://tools.ietf.org/html/rfc5789

    https://community.filemaker.com/ideas/2608
    Please upvote.

  • Avatar Steve says:

    Thanks Wim – just wondering in the Postman collection is there a way to update the {{server}} in the URL in one place without having to update each request, e.g.:

    https://{{server}}/fmi/rest/api/record/the_UI/FRUIT_utility

    I would like to change this to:

    https://localhost/fmi/rest/api/record/the_UI/FRUIT_utility

    and the same for all the other requests in the collection. Is this possible in Postman?

  • Avatar Steve says:

    I’m trying to get confirmation of the date format used by the REST API – haven’t found any mention of this in the API docs so far. I’m assuming it is MM-DD-YYYY – is that your understanding of this?

    • Wim Decorte Wim Decorte says:

      This is how a date and a datestamp field are returned:
      “date_field”: “09/07/2016”,
      “timestamp_field”: “09/07/2016 10:22:40”,

      Note that the Data API makes no attempt to match the FM field data types to JSON data types, it just sends everything as text, so everything is preserved as it is in FM.

  • Avatar Steve says:

    Thanks Wim – I was more concerned with the request/find format when searching on a date – do you have to specify the date in the MM/DD/YYYY format instead of your local format, e.g. DD/MM/YYYY in the UK?

    Also do you know if each Data API request triggers the OnFirstWindowOpen script trigger and the OnLastWindowClose as well?

    • Wim Decorte Wim Decorte says:

      Hi Steve,

      I haven’t done any research into search locale formats, but since FMS expects everything as json text and responds in nothing but json text format I would assume that you can specify it in your locale.
      Calls to the Data API do not trigger any scripts in FMS, the Data API talks straight to the database engine and does not pass through the FMS scripting engine.

  • Avatar Steve says:

    Thanks Wim – from my testing here with UK dates if I have a date entered in the database as 30/11/2017 it is returned in US format:

    “Date”:”11/30/2017″

    And when performing a find query it only works when specifying the MM/DD/YYYY date format for a date.

  • Avatar Job says:

    Great article. Learned a lot, just what I needed actually. Really appreciated you included the FM files and info about Postman.
    Thanks!

  • Avatar Pitisak Walbolt says:

    Hello – Just starting to do some work with the fm api. this is a great article that helped me get started.

    One thing I am trying to do is to make one call with mutliple rows. Example my first call post to create a record for a parent record. Now my second call goes to a child table that could have 1 record or multiple records. Will the filemaker Api handle this wor do I have to send each child record separately?

    • Wim Decorte Wim Decorte says:

      Hi, glad you liked the article.
      If there is a portal on your target layout then you can manipulate the existing child records in one call. I believe you can only create one related record per call though.

Leave a Reply