FileMaker 18 New Features: Data API
FileMaker 18 is finally out and with it comes new features and improvements to the FileMaker Data API. A new category of API calls has been added to allow developers to request metadata from a FileMaker host. These new API calls return information regarding:
Two additional API calls have also been added:
These new additions expand the ways that we can work with FileMaker solutions via the FileMaker Data API. Throughout this article, we will dig deeper into what these new API calls mean and how can they be used.
Quick Note
If you are a beginner at using the FileMaker Data API, I suggest that you visit the FileMaker help section to learn more. This guide provides an overview of what the new features are to the FileMaker Data API. It will not discuss details of API calls that were introduced in previous versions of FileMaker Server.
During this walkthrough, I will be using screenshots from a personal solution to demonstrate the requirements and results of each API call. You should be able to view the API call URL and its parameters on the left side of the screenshot and its results on the right side. The database that I am using to connect with is a Tasks starter solution that FileMaker provides when creating a new solution. Now that this has been explained, let’s dive into the new FileMaker Data API features.
Product Info
The Product Information API call allows us to extract metadata from FileMaker Server or FileMaker Cloud for AWS. It is one of the simplest calls to make. The only data that is required to create the API URL is the FileMaker Data API version number.
Once the call has been made and it has been successful, you should see call results similar to what is seen in my example on the right side. The server provides some general information on itself including when the server was built, what the version number of the server is and some date and time format information.
Database Names
The Database Names API call request provides a list of the databases that are hosted on FileMaker Server. As we have seen in the previous API call, the API version number is the only requirement when creating the call URL. However, you have the option to pass in header parameters such as an Authorization Token to view databases based on account credentials if the FileMaker Server has “Filter Databases in Client Applications” enabled. Otherwise, if it is disabled, then you should see all hosted databases with the following criteria:
Databases open or paused on the server.
Databases that have an account with the extended privilege fmrest enabled.
Above is a screenshot that displays the data that is returned after this call has been made. It should return the hosted database names in a JSON Object which will reside in a JSON List. A question you might be wondering is what kind of interaction might occur if these databases resided in a subfolder. Would data be returned to indicate whether a database resided in a subfolder or not? Well, no. It would still return a list of databases as you see in the screenshot and would disregard folder structures. However, we will not see the same interaction from the other metadata API calls.
Layout Names
Now, let’s dive into the Layout Names API call request. This request allows a developer to extract a list of layouts residing in a database that you have an ongoing session with. This means that you will need to log in to the database via the FileMaker Data API and obtain a session token. With this session token, you will be able to meet the authorization requirements for this call. You will also need to define the database name in the API URL.
From the screenshot above, we can see that the result includes information about the layouts and layout folders for the database. For folders, the JSON object will include an “isFolder” key with a true value and a “name” key with the name of the folder. The folder object will include an array of layout name objects.
Script Names
The Script Names API call request is very similar to the Layout Names API call request. Instead of receiving a list of the layout names, what we will be receiving is a list of the script names that a connected database holds. This call accepts the same parameters as the Layout Names call request. One difference regarding the data received is that all JSON objects include an “isFolder” key that will be true for folders and false for scripts.
Layout Metadata
The final new metadata request returns detailed information about all of the objects on a layout. To make this request, you will need to specify the database you want to connect to and the layout that you want to retrieve information about as parameters. We will also need a session token for that database as well. Once the request is made, the returned result will be a JSON object with information about fields, portals, and value lists.
From the above image, you can see what kind of data is returned. For the field metadata section of the JSON object, we can see it displays attributes of the fields that reside on the layout that are not contained in portals. Each portal will be included as an object containing an array of the fields contained within the portal. For value list metadata, the result includes the name of the value list, whether the value list is a custom one or one that is based on a field, and an array of values for a custom value lists.
This API call also has an optional query parameter that allows the developer to specify a record ID to retrieve value list data based on that record. This will allow us to see value list information that is based on related data. With the information gathered from a specific record, a user might be able to re-create related value lists based on fields in other interfaces.
Overall, this call is useful to extract information for other calls. This information could be a guide on what data we should expect to retrieve when enacting any of the record GET calls. For example, if I were to use the GET Record call, I would be able to expect what data would be returned based on what is on the layout. I also could expect on a length of call depending on how many calculations, summaries or portals could be on the layout. Most of the record GET calls also have a query parameter regarding portals which we would be able to use this call to retrieve some of the portal table names need to pass into other calls.
Duplicate Record
Another addition to the FileMaker Data API is the ability to duplicate an existing record. You will need to specify the database name, layout name, and the record ID for the record you wish to duplicate. As with other Records API calls, a session token is required and options are available to run a script at various points during the request.
Once the request is complete, it should return the record ID for the newly created record. It should also return a record modification count value, which is the modId key in the screenshot. The modID always starts at 0 for a new record and is incremented each time the record is modified.
Execute Script
Finally, FileMaker has added an Execute Script API call. This will allow developers to execute scripts independently of other API calls. In previous versions of the FileMaker Data API, scripts could be executed, but only as part of other API calls, such as create, edit, delete and find. Now, we have the ability to perform scripts without tying the request to a possibly unnecessary action.
This API call requires multiple parameters to initiate the call. You will need to specify the database name, the layout name and, of course, the script name. You also have the option to pass a script parameter as a query parameter. For my example, I run a script on the hosted Tasks database to create a new task record. Once the script has ended, the ID of the newly created record is returned as a script result. You can see the script result in the response portion of the API call results above.
Take caution though. Scripts run via the API must establish their own context and should include appropriate error handling logic.
The above screenshot displays the script that I had previously called via the execute script API call. I made a modification where I am performing a find with a garbage value so an error would occur. I also changed the script result with a local variable that I declare before the find. The result I receive is seen below.
We can see that we retrieve a script error of 401 which was expected. We continue to receive the script result as well. Now let’s change the script to perform another operation after the error is thrown.
I have now re-set the local variable with the same value. After making the same API call, this is what I receive.
The script error is cleared and the script result still returns with the correct value. What you will need to remember from this is that proper error handling will need to be introduced to understand whether an error has occurred once the script has run and then properly handle the outcome. Otherwise, data may not be properly modified or returned.
Conclusion
It’s truly exciting to think about the possibilities of what could be done with these new features. One idea that came to mind was to combine the Script Names API call with the Execute Script API call. A developer could dynamically extract the list of scripts from a database and then provide an interface for users to execute any of those scripts. The following image shows a simple example of this idea.
Developers could also implement a way to track changes to layouts by comparing Layout Metadata API call results from different days. It would be interesting to see what had changed during development from one day to the next. The possibilities are endless. Let me know in the comments how you intend to use these new FileMaker Data API calls.
Jessie Cisneros is a FileMaker Certified Developer at Skeleton Key in St. Louis, MO.
About Skeleton Key
Skeleton Key develops apps on the FileMaker platform making them easy-to-integrate, easy-to-use, and quick to build and deploy. Our team of experts takes a comprehensive consulting approach to focus on learning how your organization operates. With deeper insights into the way your team works, we’re able to create an ideal solution built around your operations while forming a partnership founded on trust and transparency. We hope you found this content useful and we would love to hear from you if we can be of any further assistance.
