Learning the FileMaker Data API by trial and error.

I’ve recent­ly com­plet­ed work on inte­grat­ing the File­Mak­er Data API into a Javascript appli­ca­tion. I fum­bled around dur­ing the process and want­ed to doc­u­ment my thoughts while my impres­sions were still fresh.

The most significant issue: finding the correct documentation

I’ll start with the con­clu­sion. My search­es did­n’t sur­face the cor­rect doc­u­men­ta­tion when I began the process, so I’ll share some URLs to begin.

• The Claris File­Mak­er Data API doc­u­men­ta­tion: https://​help​.claris​.com/​e​n​/​d​a​t​a​-​a​p​i​-​g​u​i​d​e​/​c​o​n​t​e​n​t​/​i​n​d​e​x​.html
• File­Mak­er 18 Data API Guide (specif­i­cal­ly, the sec­tion labeled ​“Write File­Mak­er Data API calls”): https://​fmhelp​.file​mak​er​.com/​d​o​c​s​/​1​8​/​e​n​/​d​a​t​aapi/
• Claris ODa­ta API and File­Mak­er ODa­ta API Guide: https://​help​.claris​.com/​e​n​/​o​d​a​t​a​-​g​u​i​d​e​/​c​o​n​t​e​n​t​/​w​r​i​t​e​-​o​d​a​t​a​-​a​p​i​-​c​a​l​l​s​.html
• File­Mak­er Data API v1 Post­man Col­lec­tion: https://​github​.com/​j​o​h​n​f​m​o​r​t​o​n​/​f​i​l​e​m​a​k​e​r​-​d​a​t​a​a​p​i​-​c​o​l​l​e​c​t​i​o​n​-​f​o​r​-​p​o​stman
• FMDataAPI, a class devel­oped in PHP to access the File­Mak­er data­base with Claris File­Mak­er Data API: https://​github​.com/​m​s​y​k​/​F​M​D​a​taAPI

My Google fu rarely fails me. I can find just about any­thing when I set my mind to it. Per­haps I was off my game dur­ing the ear­ly phas­es of this project, but I sus­pect the nam­ing con­ven­tions for the Claris prod­ucts have some­thing to do with the poor qual­i­ty of my search results.

The File­Mak­er doc­u­men­ta­tion link ref­er­ences many sim­i­lar­ly named prod­ucts: Claris Stu­dio, ​“Claris Pro and File­Mak­er Pro,” ​“Claris Serv­er and File­Mak­er Serv­er,” Claris Con­nect, File­Mak­er Pro, File­Mak­er Pro Advanced, File­Mak­er Cloud, File­Mak­er Cloud for AWS, and File­Mak­er Serv­er, all with ver­sion num­bers. That not only con­fused me, but posts by users around the inter­net often speak of File­Mak­er gener­i­cal­ly, but it could be any one or all of these prod­ucts.

My discovery development process

I ran into mul­ti­ple prob­lems as I worked on my project, but I was able to cob­ble togeth­er solu­tions that worked through tri­al and error. You have the links above, but my path through the API has giv­en me a decent under­stand­ing of what is hap­pen­ing. It just took more time than I want­ed.

If you’re read­ing this, you might run into sim­i­lar prob­lems, and I hope my expe­ri­ence can help you get through these issues quick­er. The main things I’ll touch on here are:

• Use Post­man to quick­ly test your API calls
• Use a proxy to deal with CORS issues when access­ing the File­Mak­er Data API
• Access­ing files, PDFs in my case, from a File­Mak­er con­tain­er

I’m not a FileMaker developer

If you’re a File­Mak­er devel­op­er, you may mar­vel at my lack of under­stand­ing of File­Mak­er. I came into this project just want­i­ng to query an API end­point. I worked with a File­Mak­er devel­op­er who cre­at­ed all of the end­points for me in File­Mak­er. He cre­at­ed the lay­outs and exposed data in the lay­outs for me to query. Lat­er in this post, I men­tion the Users_​Api. I think this is a cus­tom lay­out cre­at­ed in File­Mak­er, not some­thing built by default in File­Mak­er. If you’re look­ing for infor­ma­tion on how to do that, I won’t cov­er that here.

Starting with Postman

I start­ed my dis­cov­ery using Post­man. I found a col­lec­tion of File­Mak­er Data API calls that I import­ed into Post­man. The col­lec­tion was extreme­ly help­ful, but unfor­tu­nate­ly, I did­n’t doc­u­ment where this col­lec­tion came from. I have export­ed the Post­man col­lec­tion, which includes some addi­tions I made, and post­ed it to a GitHub repo, File­Mak­er Data API v1 Post­man Col­lec­tion. I wish I could thank the orig­i­nal poster. Thank you, anony­mous inter­net per­son.

This col­lec­tion allowed me to start mak­ing requests to File­Mak­er in a repeat­able way.

As shown in the screen­shot above, the authen­ti­ca­tion request is the first item in the File­Mak­er Data API col­lec­tion, and that’s where I start­ed. The URL, https://{{server}}/fmi/data/v1/databases/{{database}}/sessions, includes vari­ables in curly brack­ets. I had two dif­fer­ent users set up for my tests, a user with full access and a user with lim­it­ed access. I set up Envi­ron­men­tal vari­ables for each user. Read about using Post­man vari­ables in the doc­u­men­ta­tion.

The col­lec­tion allowed me to test whether the File­Mak­er serv­er was respond­ing to my log-in attempt and allowed me to see what sort of data I could expect back. When I saw that a bear­er token was being returned, that opened up the rest of the API to me.

Now that log­ging into File­Mak­er worked, I wrote the rest of the API calls I need­ed to make, using the oth­er API calls in the col­lec­tion as a start­ing point. For exam­ple, I need­ed to query for all users (when in a ​“super admin” ses­sion), get the details of a user account (when in a lim­it­ed-access ses­sion), get a list of records for a sin­gle user, run a File­Mak­er script, and more.

For exam­ple, the screen­shot below is a work-in-progress of debug­ging a call to retrieve users from a lay­out called Users_​Api.

FileMaker & CORS headers

After the test API calls worked suc­cess­ful­ly in Post­man, I thought my job was near­ly fin­ished. I imag­ined jump­ing into Javascript devel­op­ment and sail­ing through to a fin­ished app. I just need­ed the CORS head­ers set up on the File­Mak­er serv­er to allow my app to access the API. This turned out to be a sig­nif­i­cant stum­bling point.

The File­Mak­er devel­op­er I worked with has oth­er File­Mak­er instances using the File­Mak­er API suc­cess­ful­ly, but that com­mu­ni­ca­tion was serv­er-to-serv­er, not web brows­er-to-serv­er. That’s when I real­ized I need­ed to write a proxy between my web app and the File­Mak­er end­point. CORS head­ers are not an issue when no web brows­er is in the mix.

PHP as a FileMaker proxy

Since PHP is the serv­er lan­guage I’m most com­fort­able with, that’s where I start­ed. I wrote a cus­tom proxy ser­vice that accept­ed the requests from my Javascript appli­ca­tion and then for­ward­ed them to the File­Mak­er API. Since I had full con­trol over the proxy serv­er, I could set the CORS rules I need­ed to com­mu­ni­cate between a web brows­er and my proxy.

This worked sur­pris­ing­ly well. And as a lit­tle bonus win, I cleaned up the data returned from File­Mak­er before pass­ing it back to the Javascript app.

If, as you read this, you decide you need to cre­ate a PHP proxy, be sure to check out FMDataAPI on GitHub because it might save you a lot of time. I only dis­cov­ered this project after I had my proxy near­ly fin­ished. The rea­son I dis­cov­ered FMDataAPI, though, was my last major hur­dle.

Displaying PDFs and other files from FileMaker through the API

My PHP File­Mak­er proxy deliv­ered the tex­tu­al data to my app as I need­ed, but one page of my app was a list of links to PDFs. These were month­ly state­ments the users need­ed to view.

This is the for­mat of the URL that I would receive from File­Mak­er:

https://example-filemaker-server.com/Streaming_SSL/MainDB/abcdef12345ghijkl6789.pdf?RCType=EmbeddedRCFileProcessor

Link­ing out to these URLs would not load the PDFs in the web brows­er. I need­ed my proxy to inter­cept these URLs and load the PDF instead. I for­mat­ted my request like this:

https://my-proxy-server.com/api/fm-proxy-pdf-viewer.php?token=123token456&pdfUrl=https%3A%2F%2Fexample-filemaker-server.com%2FStreaming_SSL%2FMainDB%abcdef12345ghijkl6789.pdf%3FRCType%3DEmbeddedRCFileProcessor

I’ll break this URL down into pieces.

• The loca­tion of my proxy: https://my-proxy-server.com/api/pdf-viewer.php
• The token para­me­ter is used to make requests to File­Mak­er
• The pdfUrl para­me­ter is a URL Encod­ed copy of the PDF URL pro­vid­ed by File­Mak­er

I’ve post­ed the script for the File­Mak­er PDF Proxy I end­ed up using in a GitHub gist. https://​gist​.github​.com/​j​o​h​n​f​m​o​r​t​o​n​/​5​0​7​a​f​6​c​5​b​6​4​9​a​2​a​f​e​a​f​c​7​9​9​8​8​8​4​20228

This script took a lot of debug­ging, but the piece that tripped me up the most was the need for a cook­ie jar, on line 40 in my Gist.

curl_setopt($ch, CURLOPT_COOKIEJAR, $cookieFile); // save cookies

I dis­cov­ered some­one hav­ing the same autho­riza­tion issue with file access that I was expe­ri­enc­ing in a thread on GitHub, https://​github​.com/​m​s​y​k​/​F​M​D​a​t​a​A​P​I​/​i​s​s​u​es/18, in the FMDataAPI project issues. Not only did this solve my prob­lem, but if I’d dis­cov­ered this project ear­li­er, it might have negat­ed the need for me to cre­ate my PHP proxy. Since my proxy was now com­plete, I kept it, but if you’re think­ing of writ­ing your own, I’d sug­gest check­ing out this project first.

One-time use URLs

I once again thought my project was near­ly com­plete. I was so hap­py with how things were work­ing. My Javascript app con­nect­ed with only one API but three of them: File­Mak­er, Craft CMS, and a cus­tom pay­ment gate­way. (Con­nect­ing to Craft CMS is a breeze, so I did­n’t feel the need to write a big post about that.)

I was walk­ing my client through the app, feel­ing pret­ty pleased with myself. I logged in and showed him the File­Mak­er data. It was smooth as but­ter. I opened a PDF, and it dis­played as expect­ed. I clicked around the app some more, show­ing him the pay­ment por­tion, and as I was wrap­ping up, I clicked to open the PDF again, but it failed to open. I closed the PDF win­dow and tried again. No luck again. Only dur­ing the client review did I real­ize the links to the PDF files were good only for a sin­gle vis­it.

Since I had come this far with no real doc­u­men­ta­tion to speak of, I’m not too embar­rassed by this, but I wish I had known it ear­li­er.

The solu­tion to this prob­lem was pret­ty sim­ple, though. When a user clicks the link to open the PDF, I send an addi­tion­al request to File­Mak­er to get a new URL for that PDF and silent­ly update it in the file list in the Javascript app. Now, the logged-in user can view the PDFs as much as they want.

Timing out of tokens

One of the final things I worked on in my Javascript app was to man­age the token timers. There are 3 timers I man­age in my app.

• The Javascript app user ses­sions log out after 10 min­utes of inac­tiv­i­ty.
• The File­Mak­er token will expire after 15 min­utes from the last use of the token.
• The File­Mak­er token will expire after 16 hours, no mat­ter how often it is used.

The File­Mak­er token time­outs are not some­thing I have found in the doc­u­men­ta­tion. These times were things I dis­cov­ered through con­ver­sa­tions with the File­Mak­er devel­op­er I worked with. I’m just pass­ing it along in case you’re won­der­ing about those times too.

In my Javascript app, I have three count­down timers run­ning at all times and refresh them based on user activ­i­ty in the app. If the user is active in the app for 14 min­utes but has not hit the File­Mak­er API, I silent­ly make a request to File­Mak­er to keep the File­Mak­er token active. If a user uses the app for 16 hours, I log them out, no mat­ter how much they’d like to stay logged in.

End of the brain dump

That’s all I’ve got for you on work­ing with the File­Mak­er Data API, and I wish you luck in build­ing your app if that’s why you’ve read this far. Cheers.