With FileMaker 2024 (v21), Claris unveiled powerful features and improvements aimed at enhancing data management efficiency and security. This blog post series covers the advancements in FileMaker's Data API (FM DAPI), focusing on REST and cURL, which offer developers greater control and flexibility in their applications.
We're providing a tutorial file (bzTrainer-FMDAPI) to help you learn and experiment with various REST and cURL functions using FileMaker's Data API. Enjoy exploring!
FileMaker Data API: A Brief History
This blog post series, and included tutorial files, were put together by several Beezwax developers, including Darren Burgess and Siroos Jafary. Darren and our team have been sharing resources for learning and using the FileMaker Data API, from when it was first introduced with FileMaker 16 through more recent versions.
Here are links to this series of blog posts. This can help you review the evolution of the FileMaker Data API (FM DAPI) over the years, whether you're new to FileMaker or want a refresher on how it all works.
- FileMaker 16 - FM DAPI in 'beta'
- FileMaker 17 - Official release of FM DAPI with 10 endpoints
- FileMaker 18 - 5 new metadata endpoints and nicer documentation
-
FileMaker 19 - 1 new auth endpoint;
Execute FileMaker Data APIscript step -
FileMaker 2023 (v20)- Date formats;
Save Records as PDF; bug fixes -
FileMaker 2024 (v21) - CRUD via
Execute FileMaker Data API; enhanced validation, admin, error handling and cURL; usage limits removed.
For those new to the FileMaker Data API, don't forget to toggle the 'Enabled' setting under Connectors > FileMaker Data API - General Settings within FileMaker Server. This allows you to make HTTP requests against the files hosted on the server.
REST Data API Enhancements
The REST Data API in FileMaker 2024 has received several significant updates that enhance its functionality and usability. Here’s a closer look at the new capabilities:
Write Operations to Modify Record Data with Execute FileMaker Data API script step
The Execute FileMaker Data API script step now supports various write operations, allowing developers to create, update, delete, or duplicate records. By setting the action key to the desired operation, developers can efficiently manage record data directly through the API. This enhancement streamlines data manipulation processes, making it easier to maintain and update databases programmatically without the need for switching between layouts.
Note: The metaData action in Execute FileMaker Data API is exclusively used for retrieving information about tables and layouts.
Overriding Data Entry Validation
When writing data, the new optional “options.entrymode” key allows developers to override the 'Allow user to override during data entry validation' option. By setting this key to 'user' (to follow a field's data validation requirements) or 'script' (to ignore a field's data validation requirements). Similarly, the “options.prohibitmode” key determines whether to observe or bypass the 'Prohibit modification of value during data entry' setting. Use 'script' to disregard automatic data entry rules or 'user' to adhere to them. Developers can control how validation is handled during data entry operations. This feature provides flexibility in managing data integrity and user input.
Enhanced Error Information
Error handling is crucial for debugging and ensuring the smooth execution of scripts. The updated Execute FileMaker Data API script step now returns appropriate error information via the Get(LastError), Get(LastErrorDetail), and Get(LastErrorLocation) functions. These functions provide detailed insights into errors, enabling developers to quickly identify and resolve issues.
In addition to above enhancement, the 'Set Error Logging' script step is now supported in scripts run by FileMaker Data API and FileMaker WebDirect to help you quickly identify and troubleshoot issues.
Admin Console improvements
The Dashboard tab in the Admin Console now displays the number of FileMaker Data API connections, and Windows Performance Monitor has added a client counter for the FileMaker Data API.
Unrestricted Annual API usage limits
The FileMaker Data API and OData API removed annual usage restrictions.
Starting with v21.1.1 of FileMaker Server, API usage is fully unrestricted.
Addressed Issues
Several issues have been addressed in this version to improve stability and functionality:
-
Date Format Error: Previously, specifying a value for the “
dateformats” key when using the create or update action in the Execute FileMaker Data API script step would return an error. This issue has been resolved, ensuring smoother date handling. - Unexpected Quit: An issue where FileMaker Pro would quit unexpectedly when running an Execute FileMaker Data API script step that referenced a field ending with a colon has been fixed. This improvement enhances the reliability of the application.
-
Perform Script on Server: In scripts invoked by the FileMaker Data API,
Perform Script on Server(PSoS) steps lost database access and failed if the API session ended before those steps finished. This issue has now been resolved. - File size units: FileMaker Data API usage statistics were occasionally displayed in mismatched units, such as “x TB of y GB” instead of using a consistent file size unit.
- HTTP Error handling: In older versions, the FileMaker Data API incorrectly returned an HTTP 500 status when a find record request triggered FileMaker error 401 (“No records match the request”). It now properly returns an HTTP 200 status with an empty result set instead.
-
SSL certificate’s hostname mismatch: When the Insert from URL script step was used with the “
location” cURL option, the host redirecting to a different hostname triggered an error indicating that the SSL certificate’s hostname did not match the specified URL. - fmdapi.log headers issue: The headers in the fmdapi.log file did not match the record columns. To ensure the fix is applied when upgrading FileMaker Server, delete or rename the existing fmdapi.log file.
- Windows and macOS: When there were active Data API client connections, stopping the FileMaker Data API process caused the fmwipd FileMaker Server process to terminate unexpectedly.
cURL Enhancements
FileMaker 2024 brought improvements to the cURL options available in the Insert from URL script step, expanding its capabilities for secure file transfer and AWS integration.
Secure File Transfer Protocol (SFTP) Support
The cURL option now supports SFTP, allowing for secure file transfers. Additionally, it includes the pubkey option for SFTP public key authentication, enhancing the security of file transfer operations. This feature is essential for developers who require secure communication between servers and FileMaker applications.
AWS Signature Version 4 Authentication
The Insert from URL script step now supports the '--aws-sigv4' cURL option, enabling Amazon Web Services (AWS) V4 signature authentication in HTTPS headers. This option is particularly useful for developers working with AWS services, as it ensures secure and authenticated communication. However, it is important to note that this option is not supported when the file is hosted by FileMaker Server on Ubuntu 20.
For more details, please see Supported cURL options | Claris FileMaker Pro Help.
To use AWS V4 signature authentication, specify a string for the provider and, optionally, region and service. Also, use '—user' to specify 'access_key_id:secret_access_key'. The available parameters are '<provider1[:provider2[:region[:service]]]>'.
An example Custom Function in bBox plug-in
To help take advantage of FileMaker's functionality, we introduced a custom function in our bBox utility plug-in. This function is designed to calculate the necessary URLs for three of the APIs supported by FileMaker Server: Admin API, Data API, and OData API, making your integration tasks smoother and more efficient.
For a deeper dive, check out our detailed blog post on bBox, a free utility plug-in that extends FileMaker solutions by facilitating the use of various code libraries. It supports both macOS and Ubuntu Linux and includes functions for working with Python, JavaScript, PHP, Ruby, AppleScript, Bash/Zsh/sh, XPath, and DuckDB.
Tutorial file: FileMaker 2024 (v21) Data API using REST and cURL
Check out the tutorial file for interactive examples:
Download bzTrainer-FMDAPI-2024
- Use this form to request the download [or GitHub link]
- software is named 'bzTrainer-FMDAPI-2024'
- download folder includes
bzTrainer-FMDAPI-2024.fmp12,LICENSE, andREADME.md - ~2.1 MB download
Username: admin
Password: admin
The demo file should be hosted on FileMaker Server 2024 (v21.x or later) for full functionality.
This is a simple demonstration file designed to help you get started in your understanding of FileMaker 2024's Data API and cURL options.
This file sends REST requests to itself, and so makes for a good demonstration of Data API and cURL features. To get the most out of the demo, please check out the scripts, especially execute rest request. You can also study the results of requests in the fields to the right side of each layout.
This demo uses the Execute FileMaker Data API script step with FileMaker 2024. Check out the execute data api script as an alternative way to query the Data API.
For more details on this script step, please see Execute FileMaker Data API | Claris FileMaker Pro Help.
Getting Started
- 1. Host this file on a FileMaker Server 2024 (v21.x or later)
- 2. Enter the URL or IP address of your server. Example 192.168.1.50 or hostname.your-domain.com
- 3. Enter the account name and password for the FileMaker user account that will access the API. The default for this file is already entered.
- 4. Enter the file name you wish to access, without the .fmp12 extension (default is this file).
Please see the README file included with the download for more info.
Comparing FileMaker Data API vs. OData
While the FileMaker Data API (FMDAPI) has come a long way since its introduction, there is also an alternative: OData, which we're also covering in other blog posts.
Both FMDAPI and FileMaker OData API offer methods for interfacing with web services, but they have distinct features and use cases. Here's a brief comparison, based on current versions:
FileMaker Data API (FM DAPI)
The FileMaker Data API is a RESTful service that allows web services to interact with databases hosted on FileMaker Server or FileMaker Cloud. It's designed to perform database operations such as creating, updating, and deleting records, and retrieving data in JSON format, which is widely used for web applications. This API is particularly strong in its integration with FileMaker's own environment, allowing the use of FileMaker scripts and layouts to configure and automate database interactions.
FileMaker OData API
The FileMaker OData API, on the other hand, allows FileMaker data to be accessed alongside other OData-compliant data sources:
- OData provides a uniform way to query and manipulate data sets through CRUD operations (Create, Read, Update, Delete) using standard web technologies such as HTTP.
- OData also enables you to modify FileMaker schema, for creating and deleting tables and indexes. These are based on the access privileges defined for an account.
- OData supports a range of features like filtering, sorting, and paging data, making it versatile for use in various types of applications, including integration with other services and platforms.
- FileMaker OData is well-suited for applications that need to interact with multiple database systems or replace traditional database connectivity options like ODBC and JDBC.
- The FileMaker OData API does not require the installation of additional drivers or software on the client, which simplifies deployment and maintenance.
Overall, the FileMaker OData API is well-suited for applications that need to interact with multiple database systems or replace traditional database connectivity options like ODBC and JDBC.
In other blog posts, we're covering more about OData and the FileMaker OData API.
We've described the functionality of FMDAPI and FileMaker OData API.
Be aware that performance may vary based on many factors such as the method used (FMDAPI vs. OData), the API or system being called or queried, and how data is being transferred, transacted or transformed.
If you have questions or need help, please feel free to get in touch with us at Beezwax.