RESTfm + FileMaker (Part 1 of 2)

I recently made a stand alone FileMaker app that used RESTfm to sync(read:transfer data with specific rules I’ve set up) data from a FMS hosted FileMaker file, wrapped up in the FileMaker iOS SDK 15 in Xcode – I thought I would share how this was done.

Firstly, I love RESTfm, huge wraps to Nick @ Goya for the ability to make a hosted FileMaker file into a RESTful API. This is a game changer as far as I am concerned, even though it has been around for a while, I only picked it up recently. I looked at the FileMaker PHP API and freaked out, I’m not a web developer so the RESTfm makes sense to me.

Secondly, what is a RESTful API? In my words, it’s a way to interact with data using a logical URL string. Wiki says this though.

Thirdly, why did I do this? A few reasons, I wanted our Clients to access their hosted data on an iPhone. I had iPhone layouts on the hosted file, and tried a standalone iPhone app with setting up a data source and also tried fmEasySync. All these required some hard coding and constant service (3G / 4G / LTE / Wifi ) to access the data to work.  RESTfm is a different approach, in Nicks words, “we wrote a sync engine around REST because we thought REST as a model ( single fast short connections ) was a better choice than the more heavy network connection of a full FileMaker client.” . I also needed the app to be scalable, this is an extension to a vertical solution of ours, so I wanted to roll out 1 app for all of our clients, as opposed to 100+ iterations of the app. RESTfm was the solution, users no longer had to have constant service to access the data, now they can sync the data when in service, and be without service and still access the data from the last sync. I also wanted to get an app on Apple’s AppStore using FileMakers iOS SDK.

Last but not least, RESTfm is free and there’s a support option (I am a supporter myself) : http://restfm.com/purchase and the support option includes the sync framework that Goya has developed, as well as a few other files.

OK, here’s how I used RESTfm and FileMaker.

 

Web stuff

Step 1 ) RESTfm needs to be installed on your web server under the public_html folder. The RESTfm files are here.

Step 2 ) In the RESTfm.ini.php file of the RESTfm folder, you need to edit the server address  to the address of your FileMaker Server. I did this through my websites cpanel. This can be an IP address or URL.

Screen Shot 2016-06-09 at 9.10.19 PM

Step 3 ) Install the FileMaker PHP API in to the RESTfm/FileMaker folder, RESTfm is a layer on top of the FileMaker PHP API, Goya instructions here.

Web stuff done!

 

FileMaker stuff

Step 1 ) We need to enable the PHP privilege set in the hosted FileMaker file. To do this, go to File > Manage > Security , authenticate in to the Manage Security area, then click on Extended Privileges, double click fmphp, in the Access area turn On for all Privilege Sets that you want to use RESTfm. Then press OK and save.

OK now we can access the FileMaker file, however we don’t have any layouts or fields that we can work with. We’re going to create new layouts specifically for interaction with RESTfm.

Step 2 ) Layouts | I gave these layouts a naming convention as suggested by Nick in his documentation, I prefixed the layouts with ‘restfm’. I only wanted to sync data from 2 tables, so I created 2 layouts, restfmClient and restfmTask.

Step 3 ) Fields | For the FileMaker PHP API to work, the fields that you want to interact with need to be on the layout. Only put the fields you need on these layouts. If you aren’t using the data in a field then don’t put it on the layout, it will increase the data dump you will receive from the API call.

I’m not sure what order the data is pulled down in, so what I suggest is to place the fields on the layout, and then lock them. You don’t want the order of the data to be changed. Trust me – been there, done that, not fun.

OK, we should be done with the set up, so now let’s take a look at some of the API calls.

 

The API calls

API calls work in 4 ways typically, GET, PUT, POST & DELETE. I’m gonna translate these into FileMaker terminology.

GET = Found Set (Get all records on a layout (table), or a specified found set)

PUT = Set Field (Update existing data)

POST = Create New Record

DELETE = Delete Record

 

GET Example

Ok, lets find all records where the field appFullName is Stevie Hallo, in the table Client, using the layout we’ve created called restfmClient. In FileMaker, crudely, this is Enter Find Mode, Go to Layout [restfmClient], Set Field [ restfmClient::appFullName ] ‘Stevie Hallo’, Perform Find.

Lets look at it using a RESTfm API call from within a FileMaker file.

http://server_accountname:server_username@mywebsite.com.au/RESTfm/filename/layout/restfmClient.json?RFMsF1=appFullName&RFMsV1=Stevie Hallo&RFMmax=0

Clear as mud? I thought so, lets break it down a little.

 

http://   (You can use http or https depending upon your website)

server_accountname   (We need to be authenticated by the server, this should be an account that has the fmphp privilege set activated in FileMaker Stuff Step 1.)

:   (This colon separates the accountname and password)

server_password (Password of the above accountname)

@   (This at symbol joins the accountname and password to the url)

mywebsite.com.au   (The website that you installed RESTfm on)

/RESTfm/   (RESTfm here is actually the folder where you installed RESTfm in your public_html folder)

filename   (The hosted FileMaker filename, minus the file extension)

/layout   (Joins the filename to the layout we want)

/restfmClient   (This is the layout we have created, with the fields we want on the layout)

.json?   (This is the data output type, I’ve used JSON, but you can use xml, dict, simple and a few others)

RFMsF1   (This is how we determine the field to search in, and number matches the field to a value. I think it stands for RESTfm Search Field 1)

=appFullName   (We tell RESTfm that the FIELD is APPFULLNAME)

&   (We seperate the field and value pairs with an ampersand)

RFMsV1   (We stipulate the value of that first search field, I think it stands for RESTfm Search Value 1)

=Stevie Hallo   (We tell RESTfm that the VALUE is STEVIE HALLO)

&   (We seperate other stuff with an ampersand)

RFMmax=0   (I’m telling RESTfm to max the find count to 0, which actually brings down all records, you can omit this and the prefixed ampersand and by default RESTfm brings down 25 records)

 

OK, hopefully I haven’t lost you.

 

So we have this URL string, now what do we do with it on our standalone FileMaker file? We going to use the Insert from URL script step, and insert this into a field, (which needs to be on the layout, could be off the canvas though). We need to Specify URL in the calculation that we don’t want to automatically encode URL, so uncheck this box.

Screen Shot 2016-06-09 at 10.17.57 PM

Screen Shot 2016-06-09 at 10.18.29 PM

Perfect, so now here’s a look at the (dummy) data we receive from the API call.

 

{"metaField":[{"name":"appPhoneMobile","autoEntered":1,"global":0,"maxRepeat":1,"resultType":"number"},{"name":"_pk","autoEntered":1,"global":0,"maxRepeat":1,"resultType":"text"},{"name":"appEmail","autoEntered":0,"global":0,"maxRepeat":1,"resultType":"text"},{"name":"loanwriter","autoEntered":1,"global":0,"maxRepeat":1,"resultType":"text"},{"name":"appFullName","autoEntered":1,"global":0,"maxRepeat":1,"resultType":"text"},{"name":"ModifiedUTC","autoEntered":1,"global":0,"maxRepeat":1,"resultType":"number"},{"name":"residentialAddress","autoEntered":0,"global":0,"maxRepeat":1,"resultType":"text"}],"meta":[{"recordID":"65550","href":"\/RESTfm\/filename\/layout\/restfmClient\/65550.json"}],"data":[{"appPhoneMobile":"0499 999 999","_pk":"3BEE4A5F-36D7-4760-BF0E-0B8B25BF17E6","appEmail":"test@blackframe.com.au","loanwriter":"Jane Citizen","appFullName":"Stevie Hallo","ModifiedUTC":"63599655946334","residentialAddress":"1 Pitt St SYDNEY NSW 2000"}],"info":{"tableRecordCount":"500","foundSetCount":"1","fetchCount":"1","skip":0,"X-RESTfm-Version":"3.4.0\/r4ab04a3","X-RESTfm-Protocol":"5","X-RESTfm-Status":200,"X-RESTfm-Reason":"OK","X-RESTfm-Method":"GET","X-RESTfm-Profile":"2722ms 1003.6K 128M"},"nav":[{"name":"start","href":"\/RESTfm\/filename\/layout\/restfmClient.json?RFMsF1=appFullName&RFMsV1=Stevie+Hallo"},{"name":"end","href":"\/RESTfm\/filename\/layout\/restfmClient.json?RFMsF1=appFullName&RFMsV1=Stevie+Hallo&RFMskip=end"}]}

 

Wow, that looks scary for 1 record, lets break it down. The data is in 5 sections, metaField, meta, data, info and nav.

metaField is information about the fields, is it auto entered, global, repeat and resultType.

meta is the FileMaker record ID, and also a href link that can be useful.

data is colon separated pairs of filename and value, this is what I was after.

info is relative to the table, found set, fetch count and some RESTfm info, including the status of 200 in the above example, meaning successful API call.

nav is further information from RESTfm.

From here we sift through the data and set fields in our local FileMaker file, I’ll get to this in Part 2 of this blog next week, as well as other API calls such as PUT, POST & DELETE from within FileMaker.

Here is a video of syncing 262 records, this could be quicker but I’ve chosen to show the user incrementally where they are in up to in the sync as a percentage.

Happy FileMaking!

Comments (4)
  1. Alec Gregory says:

    This is a great post! I’ve been meaning to look into restFM for ages and this is the perfect nudge. Looking forward to part 2.

    One thing I wanted to ask about was the username and password in the URL string. I assume that this method would be secure using SSL as SSL prevents interception of the data in transit and the URL is never exposed in the FM Go app so there is no risk over the shoulder snooping. Using HTTP this would be vulnerable to interception though.

    Do you think HTTPS would remove the need for messing around with oauth? Or is that something you’ve looked into and would like to implement? I have done so and been put off in the past.

    1. Damien Kelly says:

      Hi Alec, thanks for your comments!
      I love restFM, it’s really opened up FileMaker a lot for me.
      Regarding username and password, you can have this bypassed by using a key (UUID), then you need to map that in your rest.ini.php file to a username and password.
      Regarding SSL & HTTPS – I will ask the question to Nick @ Goya and let you know his response.
      I don’t use OAuth as using FM Go we can’t set headers, so I believe it has to be a URL string.
      Damien.

      1. Damien Kelly says:

        Hi Alec, Below in bold is the responses from Nick @ Goya:

        One thing I wanted to ask about was the username and password in the URL string. I assume that this method would be secure using SSL as SSL prevents interception of the data in transit and the URL is never exposed in the FM Go app so there is no risk over the shoulder snooping. Using HTTP this would be vulnerable to interception though.
        Yes. It’s standard basic auth, so you should use HTTP. Normally the username isn’t in the url, but is passed separately.

        Do you think HTTPS would remove the need for messing around with oauth? Or is that something you’ve looked into and would like to implement? I have done so and been put off in the past.
        OAuth where? We have no OAuth in FileMaker, nor can most OAuth services connect via native FMP calls.

        One thing to remember here, is that I am using restFM with a standalone FM Go app. I’ve used it for web and iOS native apps, in which case you can set headers and use other types of authentication.

        Thanks,
        Damien.

  2. Hammer says:

    Great stuff. I want to have a crack at restfm for field solutions. This will be a good reference.

Leave a Reply

Your email address will not be published. Required fields are marked *

ARE YOU READY? GET IT NOW!
Get in touch.
Fill in this form, and we will get back to you.
Thanks!
We've received your info and we'll be in touch soon.
PGlmcmFtZSBzcmM9Imh0dHBzOi8vcGxheWVyLnZpbWVvLmNvbS92aWRlby8yMDMwNDI4MzUiIHdpZHRoPSIxMDAlIiBoZWlnaHQ9IjEwMCUiIGZyYW1lYm9yZGVyPSIwIiB3ZWJraXRhbGxvd2Z1bGxzY3JlZW4gbW96YWxsb3dmdWxsc2NyZWVuIGFsbG93ZnVsbHNjcmVlbj48L2lmcmFtZT4=