In Development, Web Development

Official FileMaker Data API

In FileMaker 16 we were introduced to the trial version of the FileMaker Data API, but with 17 the Data API is now live and ready to take the place as FileMaker’s Custom Web Publishing technology of choice. With the removal of the ability to control the PHP or XML API from the FileMaker Server Admin Console and only allowing you to enable/disable it via the command line, it’s pretty clear that FileMaker sees the Data API as the future.

The 2 biggest additions to the Data API are the ability to run scripts and the ability to upload directly into a container field, but they’ve also completely modified every single call from the trial version. Most of the changes are small, but they are worth going over, and you’ll want to update before September 27, 2018 as that is when the trial of the Data API expires for FileMaker Server 16.

Data Available per User

The amount of data you’ll have available is 2 GBs per user, per month, and will be shared and tracked annually.

FileMaker Data API - Data Available per User

You can view your current data usage on the FileMaker Server Admin Console. Keep in mind that transferring lots of container data could use your data faster.

Enabling Data API

To use the Data API, you’ll need to enable it in a few places. If you are using FileMaker Cloud the Data API will be enabled by default, but if you are using FileMaker 17 Server you’ll need to enable it in the admin console. Once logged in you can find the setting under Connectors > FileMaker Data API. You’ll also have to enable the privilege set for the account you’ll be signing in with and ensure it has “Access via FileMaker Data API – FMS only (fmrest)” checked under file > manage > security.

FileMaker Data API Admin Console SettingAuth Changes

The FileMaker Data API now uses a more standardized authentication method. You’ll still have to get a session token from FileMaker that is good for 15 minutes, only instead of passing the username and password as in your post body, you’ll need to send them as a basic authorization header where the username and password are base64 encoded. You’ll also have to send an empty JSON object in the body.

-X POST 
 https://{{server}}/fmi/data/v1/databases/{{database}}/sessions 
 -H 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' 
 -H 'Content-Type: application/json' 
 -d '{}'

Results:

{
 "response": {
    "token": "41a699b37017c9fa10d140e4bf820727f57b2447036dcdd821"
 },
    "messages": [
 {
    "code": "0",
    "message": "OK"
 }
 ]
}

You can download Postman to test API calls, which is the tool used in this article’s video. You can also download the Postman collection at the bottom of this article to help you get started making REST calls.

Each additional call to work with the data will require that you pass the token in the header. Instead of using the custom FM-Data-token headers now, you’ll use standard Authorization headers, and you’ll now have to prepend “Bearer” before your session token.

-X GET 
 https://{{server}}/fmi/data/v1/databases/{{database}}/layouts/{{layout}}/records 
 -H 'Authorization: Bearer 41a699b37017c9fa10d140e4bf820727f57b2447036dcdd821'

Data API Scripts

You can now run a FileMaker script using the Data API, which is crucial to making an awesome web solution work with FileMaker, but there are some quirks to keep in mind. For instance there is no Run Script command; instead, you can call up to 3 scripts per request:

  • Pre-request
  • Pre-sort
  • After-sort

And you can only run scripts for the following commands:

  • Create Record
  • Delete Record
  • Get Record
  • Get Records
  • Find Records

We recommend that you use the Create Record command when you want to run a script, and create a record in a log table to keep track of all the script commands that are coming into your FileMaker system. The other issue with running a script from some of the other commands is that if you do not find any records, your script and pre-sort script will not run. The pre-request script would still run though.

Uploading Into Container Fields

A new trick that FileMaker has learned, that no previous Custom Web Publishing API could do, is upload directly into a container field. With past APIs your best bet was to upload to your web server and then send the url location of the upload and have a FileMaker script Insert from URL that location. Now you can upload directly to a container field. To do so you’ll need to post the data to a URL that specifies the layout, record, container name, and container repetition. This is also the only API call that requires the content-type header to be set to multipart/form-data. And finally the cURL key name needs to be “upload”

-X POST 
https://{{server}}/fmi/data/v1/databases/{{database}}/layouts/{{layout}}/records/{{recordId}}/containers/{{containerFieldName}}/{{repetionNumber}}
-H 'Authorization: Bearer 41a699b37017c9fa10d140e4bf820727f57b2447036dcdd821' 
-H 'content-type: multipart/form-data' 
-F 'upload=@C:\Users\Administrator\Pictures\test.png'

Responses

The responses have changed a bit too. As you can see below, in 17 the response now puts all data in response.data, and error codes are now located at messages[0].code implying you could have multiple errors returned.

FileMaker 16

{
  "errorCode": "0"
  "data": "[{
    "fieldData": { 
      ... 
    },
    "portalData": {  
      ...
    }
  },
  "modId": 2, 
  "recordId": 123
  }]"
}

FileMaker 17

{
  "response": {
    "data": [
    {
      "fieldData": {         
         ... 
      },
      "portalData": {
         ... 
      },
    "modId": 2, 
    "recordId": 123
    }
  ]
  },
  "messages": [{"code":"0","message":"OK"}]
}

It will also now always return a message whether there was an error or not and will return “OK” if there were no errors. Grouping the data and messages this way helps to separate things a bit nicer and gives more flexibility to add additional metadata in the future such as field and layout information which was available in previous CWP APIs.

Why All the Changes?

Although the FileMaker Data API has changed quite from the trial, the changes help make the API similar to the Admin and Cloud API, making it easier to learn them all. Also the addition of the v1 in the URL paths is important for ensuring FileMaker is able to make changes in the future without breaking existing integrations, and simply have new integrations use the v2 path etc as new versions are released.

By moving everything towards industry standards it makes it much easier to have web developers integrate with FileMaker as they don’t have to learn a custom API–they just use the same restful API calls they use to integrate with any other software out there–which will ultimately result in better and more web integrations.

Conclusion

Now that the FileMaker Data API is officially live, we recommend using it for all future web integrations. You should also consider switching current web integrations over to the Data API as the XML and PHP APIs will likely be deprecated in future versions. Contact us if you need help integrating with the Data API.

 

Did you know we are an authorized reseller for FileMaker Licensing?
Contact us to discuss upgrading your FileMaker software.

 

DownloadDownload FileMaker Data API Postman Collection

Please complete the form below to download your FREE FileMaker Data API Postman Collection.

FileMaker Go Sensors