This blog post is the first in a three-part series about the FileMaker OData API, highlighting key features that make it an exciting addition to the Claris FileMaker platform.

_{Part 1: An Introduction to FileMaker OData}

I had the opportunity and pleasure to take a one-week dive into the FileMaker OData API. The objective was to gain as much familiarity as possible, then share what I learned at the December 2020 DIGFM meeting.

By the end of the week, and during the DIGFM session, a few things became apparent:

• FileMaker’s OData feature set offers rich and attractive capabilities.
• There is much developer interest in OData for FileMaker, and yet it still feels new to most of us in the Claris FileMaker developer community.
• Veteran FileMaker developers tend to frame their initial understanding of OData by comparing it to the FileMaker Data API.

With the above in mind, I’d like to share some of the knowledge gained, to help you take your own first steps with FileMaker OData (or “FM OData”, for short). It’s also important to note that OData is not fully supported by its initial release in the FileMaker Server 19 product line. It’s Linux and FileMaker Cloud-only – lacking Windows or macOS support on FileMaker Server – at least to start.

This introductory blog post is the first in a three-part series. It aims to provide an overview of FM OData highlights, setting the stage for more hands-on topics covered in follow-on posts.

Some Background

FM OData is the latest addition in a lineage of technologies that expose FileMaker data through an API. Like its predecessors, Custom Web Publishing (CWP), and the FileMaker Data API, it is enabled at the FileMaker Server level, and it is accessed via HTTP requests.

At the time of this writing, FM OData support is available for Claris FileMaker Cloud, as well as Linux deployments of Claris FileMaker Server.

Similarities to FileMaker Data API

As mentioned above, many FileMaker developers are taking their first look at FM OData through the lens of their experience with the FileMaker Data API. Doing so is a logical starting point, as there are foundational similarities between these two technologies.

FM OData and the FileMaker Data API have much functionality in common:

• Both are a service enabled at the FileMaker Server level.
• API requests are made via HTTP request/response.
• The request/response payload format uses JSON.
• Both provide access to reading and writing data, including container data.
• Both have the ability to invoke FileMaker scripts, including the option to supply a script parameter.
• Both enforce the permissions set up in a solution’s privilege sets, thus providing standard and familiar control over data access.

Breaking New Ground with Powerful Features

Shifting our perspective to look at the distinctive set of features that FM OData brings to the table, it is easy to appreciate why it has been drawing the attention of many FileMaker developers.

Features, as a collection, that set FM OData apart:

• FM OData is built upon OData, an established and widely-used protocol.
• The API supports both JSON and XML message formats.
• The API includes operations for updating database schema.
• FM OData requires neither layout, nor layout object, references.
• FM OData supports powerful batching and transactional features:
  • Perform multiple operations within a single API request.
  • Perform collections of operations transactionally, i.e. if one operation fails, then all changes are reverted.

Not all of the above features are new to the FileMaker platform. But, what makes FM OData so compelling is that it may be the first FileMaker API to offer all of the above features under the umbrella of one single API.

What Does This Mean To An API Beginner?

For those who may be new to any kind of API for accessing FileMaker, let’s take a step back from the “compare and contrast” perspective, and list some of what OData makes possible, without reference to any other technology.

What are some basic tasks that are possible with FM OData?

• Retrieve individual record data in JSON format
• Use a single request to retrieve data for multiple records
• Qualify requests with filtering, to match target records
• Receive any returned record data in custom-sized batches
• Create, update, and delete individual records in a table
• Invoke a FileMaker script, and receive the returned result

What are some advanced tasks that are possible with OData?

• Use a single request to update an entire set of records
• Mix and match operations (new record, edit record, delete record) within a single request
• Perform atomic updates, where, in order for any update operation to be committed, all updates must succeed, thus ensuring transactional integrity

How Do I Get Started?

Interested in learning about FM OData in a more hands-on fashion? Below are some of the basics that you will need to get started.

Recommended Technical Background

• Familiarity with basic HTTP requests and responses
• Facility with JSON
• Familiarity with an HTTP tool such as Postman, or similar
• Ability to follow documentation and examples (see below)

Documentation

• Claris v.19 OData API documentation
• OData v.4 Protocol documentation
• Table of comparison operators for OData filter operations

Why Might I Prefer the FM Data API?

FM OData is a very promising technology. It’s something that many FileMaker developers are looking at with excitement. Still, there are currently reasons why one might prefer to use the FileMaker Data API over the FileMaker OData API.

• Availability: In the initial release, FM OData is available exclusively on FileMaker Cloud, and Linux FileMaker Server deployments. Currently, it’s not supported on Windows and macOS server environments.
• Container Data: Both the FM Data API and the FM OData API provide easy access to container data stored in a FileMaker table. Currently, downloading container data via the Data API does not count against any data metering allotment in FileMaker licensing. In contrast, all data downloaded via the FM OData API, including container data, counts against this metering allotment.

What Comes Next?

Part 2: OData – Examples, Tips and Nuances
_{(with demo file)}

Part two of this blog series will introduce a demo file with example OData API requests via FileMaker, and will also cover a few lessons learned related to executing OData API queries.

Part 3: OData – Transactional Operations

Part three of this blog series will conclude the series with an introduction to the exciting world of OData transactional operations in a FileMaker context. [Note: (Jan 27, 2023) The introduction of native Script Transactions in the FileMaker platform gives us a new starting point for transactional operations.]

Thank you for your interest! I hope this helps you with your FileMaker Development.

   – Steve