Using REST and cURL with FileMaker Server 18’s Data API

Well, here we are again! With the release of FileMaker 18 we get the third version of the FileMaker Data API. This version brings an iterative advancement in features while maintaining the core functionality that was introduced with V1 of the API in FileMaker Server 17.

I’m following suit with an iterative advancement of my previous blog posts about the Data API (here and here).

NOTE: We’ve updated this series of blog posts and demo files to cover FileMaker 19:

Using REST and cURL with FileMaker 19’s Data API
As you would expect, I have updated the demo file, for use with FileMaker Server 18, and made it available below for your enjoyment and edification.
Demo - FM 18 Data API and cURL Options

The FileMaker Data API

This may be a good time for you to go back and review the previous blog post to get familiar with the basics of the FileMaker Data API. Just to note hear though, the Data API is a feature of FileMaker Server, and so the demo file you can download below needs to be hosted on Server 18 to work.

Before we get on to what is different in FileMaker 18, let’s look at what is the same. Here is the list of similarities—there may be as-yet-undiscovered behavioral differences that we have not uncovered yet:

  • The major endpoints that were available in FileMaker Server 17. In fact, I did not have to make any changes to the demo file to get the basic CRUD endpoints working with FMS 18.
  • Authentication remains the same as well, by passing a base64 encoded string that concatenates credentials as: ‘username:password’ and passes that string in an ‘Authorization: Basic’ header.

What’s new in the FileMaker 18 Data API? There are several new features worth summarizing. I have also updated the demo file to illustrate them.

Documentation

The docs available at https://{your-server}/fmi/data/apidoc/ have gotten a major cosmetic overhaul using responsive web design. They are significantly more organized and easier to read and navigate.

Version designation

Endpoint URLs now have an option to include ‘vLatest’ rather than just ‘v1’. This suggests that FileMaker will continue to maintain older versions of the API with subsequent releases of the product, allowing applications to be built against a particular version or against the ‘vLatest’ version.

It’s useful to note here that FileMaker Server 18 did not iterate the version number of the API even though changes were made. This seems consistent to me in that there were no changes made to the endpoints available with FileMaker Server 17. So, applications built on the FileMaker Server 17 version of the API should continue to work if they are migrated to FileMaker Server 18. You are going to test your apps in the new environment first, right?

What is not apparent here is how long FileMaker Inc. will support a particular version of the API. It is entirely possible that V1 will be deprecated in future releases of FileMaker Server. Plan accordingly!

Metadata

The FileMaker Server 18 metadata endpoints return information about the server and its hosted files. There are 5 metadata endpoints. See the demo file for details regarding the endpoint URL and cURL options.

Product Info

This endpoint provides basic information about the FileMaker Server such as time and date formats and the server version number. A simple GET request against the endpoint URL will return the response without any authentication required.

Database Names

This returns an array of the names of open databases hosted on the server. The cURL options for this endpoint use an authorization header that includes a base-64 encoded string combining the username and password (username:password) for any hosted databases. Login and use of the resulting authentication token is not required.

-X GET --header "Content-Type: application/json" --header "Authorization: Basic cmVzx8sXN0"

Note that if the ‘Filter Databases in Client Applications’ setting in the Server Admin Console is set to ‘enabled’ then the endpoint will only return the databases that allow access using the provided credentials.

Layout Names

Returns an array of layout names for the database application provided in the endpoint URL. Login and an authentication token is required.

Script Names

Returns an array of script names for the database application provided in the endpoint URL. Login and an authentication token is required.

Layout Metadata

Returns metadata regarding the fields on the layout specified in the endpoint. This endpoint also requires an authentication token. Two objects are returned in the ‘response’ property: one is an array of field objects on the layout and the other is an object representing each portal whose value is the array of fields in the portal. Each field object in the array of fields provides several properties of that field:

{
  "autoEnter" : false,
  "displayType" : "editText",
  "fourDigitYear" : false,
  "global" : false,
  "maxCharacters" : 0,
  "maxRepeat" : 1,
  "name" : "server_address",
  "notEmpty" : false,
  "numeric" : false,
  "repetitionEnd" : 1,
  "repetitionStart" : 1,
  "result" : "text",
  "timeOfDay" : false,
  "type" : "normal"
}

Duplicate Record

This one is pretty straightforward and self-descriptive. Duplicating a record is accomplished by issuing a POST request to an endpoint that contains the record ID of the record in question. Like this:

https://{your-server}/fmi/data/{version}/databases/{database}/layouts/{layout}/records/{recordId}

Now if you are observant you may have noticed that the endpoint URLs for getting, updating, deleting and duplicating a record are all the same. What is different is the HTTP method used in the cURL options. Respectively, that would be GET, PATCH, DELETE and POST. Check the API call results in the demo file to see this in action.

Download the Demo File

Download the unlocked demo file here.

Username: admin
Password: admin

Good luck and please do reach out to me if you have questions or comments!

darren_b(at)beezwax.net

Leave a Reply