As y’all probably know by now, FileMaker 17 has been released, including the first production edition of FileMaker Server’s Data API. This API was originally released with FileMaker 16, but only as a “beta”, expiring September 2018. As you might expect, the FileMaker 17 Data API introduces significant changes. This means that any applications written against the FM 16 Data API need to be refactored for compatibility with FileMaker 17. And that’s the work we’re here to do!
Refactoring The FileMaker Data API Demo
Don’t despair! I have done the work for you of refactoring the demo file I released for the FM 16 Data API. The basic mechanics of working with a Data API and the demo file are fundamentally the same, so I am including here the relevant bits from the previous blog post for convenience. Special thanks to Beezwax’s UX designer Mekuria Getinet for the demo file UI redesign and to FileMaker developer Andrew “Red” Witschonke for implementing such.
First, get familiar with REST
Let’s start by getting familiar with REST! First off, I’d like to limit the scope of this post to understanding FileMaker’s implementation of REST, not REST in general. If you need to start from the beginning, I would suggest this REST API tutorial. Frankly, I just chose this from a Google search for “REST API Tutorials”. I would suggest you do the same and review a variety of materials until you get it.
Ok, thanks for coming back. Now that you understand the basics, let’s dig into the particulars of FileMaker’s implementation of a REST API. It is not always readily apparent how to structure the syntax for successful API calls. After quite a bit of fiddling and trial-and-erroring, I believe I have figured most of it out. So you get to benefit from my suffering. Lucky you!
What does the FileMaker Data API do?
The Data API provides all of the basic CRUD operations (Create, Read, Update, Delete) against your hosted FileMaker data. Note the emphasis on hosted as this is a feature of FileMaker Server and its ability to respond to REST requests for your hosted FileMaker solutions and return a data response in JSON format. This will not work on an un-hosted FileMaker solution.
Since FileMaker Pro 16, the client product ships with additional cURL options in the Insert from URL script step. This upgrade brings the FileMaker client up-to-date with an ability to interact with REST APIs without the use of a plug-in. This is important, because in the sample file available below, we are leveraging the new cURL options to allow a FileMaker solution to talk to its own hosted Data API, giving a solution the power to interrogate and alter its own data through the API. The sample file is a great way to learn how to work with both the cURL options and the Data API.
Getting Started
So let’s get started. First, download and host the demo file (user: admin, no password) on FileMaker 17 Server. Note that to make the Data API available for a hosted solution, you need to enable such in the privilege sets that require Data API access. In the sample file, I created an account and assigned it to the Data Entry Only privilege and activated the Access via FileMaker Data API extended privilege for Data Entry Only. (The full access account for the file is ‘admin’ with no password)
Note that in production, you should create a dedicated privilege set for Data API access, and limit the privileges so that the Data API user account only has access to the solution resources dictated by your requirements.
The REST Layout
Nearly all of the REST calls you will make to a FileMaker solution require that you pass in the name of a specific layout. Placing fields and related data portals on this layout will define the data that you can interact with for all of the CRUD operations. In the sample file, this layout is called rest_layout. Those of you familiar with using the PHP API for FileMaker will understand this concept, as the PHP API also requires a specified layout that defines the data access functionality to the API.
The Sample File
From here on out, I suggest you host the sample file on FileMaker Server 17 and dig in to the demos provided there. Make sure you use FileMaker Pro Advanced 16 or 17 to access the file—17 is recommended as the file was created using FileMaker 17. (Note: Don’t use the file itself in production applications. It was created using FileMaker pre-release software).
The sample file walks thorough most of the functionality provided by the Data API and clearly illustrates the cURL syntax required to execute Data API calls using the Insert From URL script step.
The sample file (check out the scripts!), plus the documentation for the Data API (link provided in the sample file) and cURL options will help you develop an understanding of these new features of FileMaker Server and FileMaker Pro Advanced.
Note that the sample file is a learning resource, not an example of robust production-ready code. In the first tab of the sample file you will need to enter server and account information. This is required for the demo to work.
What’s New in the 17 Data API
The 17 Data API does have a few new features that are worth calling out. The details of these features are all in the demo, and here is a list of things to look out for:
- All of the endpoints have changed. Most notable is that the endpoints all have a version number embedded in the URL. This is good, and should signal that FileMaker will continue to maintain old versions of the API since developers will be building applications that are dependent on a specific API version.
- The log in endpoint passes credentials in a base-64 encoded string.
- You can create a record and related child records all with one request to the API. This is pretty cool. See the Create tab in the Demo. Lots of great implications for this feature. Stay tuned!
- You can run FileMaker scripts with script parameters from the API. Also pretty cool. Three different scripts as a matter of fact. See the Scripts tab in the demo.
- The API now supports container field upload. There are a few tricky bits with this endpoint. See the demo!
Good luck and please do reach out to us if you have questions or comments!
darren_b(at)beezwax.net
(The full access account for the file is ‘admin’ with no password)
3 thoughts on “Using REST and cURL with FileMaker 17’s Data API”