What is the FileMaker Data API?

FileMaker Server 17 and 18 now offers REST access to your FileMaker databases. There’s more about that how this impacts PHP developers here.

The bottom line is that to use REST as part of your PHP solution, you would usually need to write a series of cURL functions and you would have to manually manage connecting & disconnecting from your server, and saving your tokens.

This is a pain!

We know it’s a pain, because we cut our teeth rolling REST functionality into soSIMPLE Calendar.

 

FREE fmREST.php

Simplifies & manages PHP connections to FileMaker 17’s REST-based Data API.

We created this class file to make it easier to manage dynamic REST sessions for soSIMPLE and our custom development. The goal of the class file was to help PHP developers start using the new REST engine as quickly and easily as possible.

We’ll also be updating it with new features. If you’d like to add something to it, please let us know.

What fmREST.php does:

    • Makes every REST call available as a PHP function.
    • Automatically login into FileMaker Server whenever you call any REST functions
    • Saves your token for 15 minutes to reuse
    • Checks for a broken or disconnected token and automatically reconnects and runs your function again
    • Includes a sample file illustrating all the functions
    • Works in FileMaker 17 & 18 – features that are new to FileMaker 18 will gracefully fail and return an error in FileMaker 17

Where do I get it?

You can download the fmREST class file here.

(Update: this is now linked to our GitHub repository for better community participation.)

How do I use it?

Please note, a new version of the fmREST class file was uploaded on May 23, 2019 to support FileMaker 18’s new features. This documentation refers to the new version.

1. Install the file

Install the class file by putting the file “fmREST.php” at the same location as your custom PHP page, or anywhere in your include path.

Include the file in your php file by adding the line:

include_once ('fmREST.php');

And don’t forget to set the extended privilege for your FileMaker file.

2. Call the class:

$fm = new fmREST ($host, $db, $user, $pass [, $layout]);

You can also set the parameters separately

$fm = new fmREST ();

$fm -> host = 'myhost.com';

$fm -> db = 'my database.fmp12';

$fm -> user = 'admin';

$fm -> pass = 'mySecretPassword';

Note: layout is now optional when setting up your connection. If you set it here, it will be used as a default for each function, or you can include the layout when calling the function.

3. Call your functions:

fmREST will automatically log in for you as necessary, as each function is called.

Important note: since we use a cookie to keep track of your token, your first function, or a specific call to the login function should be called before any visible content on the page.

How the functions work:

The functions that are part of this class use the same name and the same construct as the Data API. The only substantial difference is that you can pass the parameters as either JSON strings, or as PHP arrays. We find that native PHP arrays have been the easiest method.

For specific reference of the expected parameters, and results refer to the API documentation, located on your FileMaker Server. The documentation is located: https://<your server>/fmi/data/apidoc/. There’s also a wealth of information here:

For FileMaker 17: https://fmhelp.filemaker.com/docs/17/en/dataapi/

For FileMaker 18: https://fmhelp.filemaker.com/docs/18/en/dataapi/

Function Reference:

WORKING WITH FILEMAKER 17:

The class file is set to work with FileMaker 18 by default. To work with FileMaker 17 instead of FileMaker 18, change the following two settings, right after $fm=new fmREST() call:

$fm -> version = "v1";

$fm -> fmversion = 17;

 

LOGIN:

$result = $fm -> login (); 

notes:

  • We use the user name and password from when you instantiated the class. This is the only function that doesn’t take parameters the same way as the API Doc.
  • You don’t need to call this explicitly. It will be called automatically whenever any data function is called.
  • Whether explicitly called, or part of another function, the login should happen before any content is shown on the page. This allows the class file to set a cookie, which in turn allows successive call to use the same token.

LOGOUT:

$result = $fm -> logout ([token]); 

notes:

  • The token parameter is optional. fmREST will use the token stored in your cookie if you don’t provide one.
  • We don’t log out automatically when functions are called. Doing so would add to the overhead of every call, defeating the purpose of managing tokens.
  • FileMaker Server will automatically disconnect you after 15 minutes, or you can call this function to manually disconnect the session.

CREATE RECORD:

FORMAT: $result = $fm -> createRecord ( $data [,$layout]) ;

 

EXAMPLE:

$record['my_field_name'] = 'my_field_value';

$record['another field'] =  'another value';

$data['fieldData'] = $record;

$data['script'] = 'a script I want to run';

$data['script.param.'] = 'a parameter to pass for the script above';

$result = $fm -> createRecord ($data); 

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • please note how the record data is an array of fields, wrapped within another array
  • all field data needs to be wrapped in quotation marks – even number fields
  • scripts can be set to run during specific parts of each routine. See API docs for more details.

DELETE RECORD:

FORMAT: $result = $fm -> deleteRecord ($recordId [, $layout]);

 

EXAMPLE:

$recordId = 1234;

$result = $fm -> deleteRecord ($recordId); 

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’];
  • scripts can be set to run during specific parts of each routine. See API docs for more details.

EDIT RECORD:

FORMAT: $result = $fm -> editRecord ($recordId, $data [, $layout]);

 

RESULT:

$recordId = 1234;

$record['my_field_name'] = 'my_field_value';

$record['another field'] =  'another value';

$data['fieldData'] = $record;

$result = $fm -> editRecord ($recordId, $data); 

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • please note how the record data is an array of fields, wrapped within another array
  • all field data needs to be wrapped in quotation marks – even number fields
  • $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’];
  • scripts can be set to run during specific parts of each routine. See API docs for more details.

GET RECORD:

FORMAT: $result = $fm -> getRecord ($recordId [, $parameters, $layout]);

 

EXAMPLE:

$recordId = 1234;

$parameters ['script'] = 'my script name';

$parameters ['script.param'] = 'a parameter for that script';

$result = $fm -> getRecord ($recordId, $parameters); 

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’];
  • scripts can be set to run during specific parts of each routine and other parameters can specify portal data returned and more. See API docs for more details.

GET RECORDS:

FORMAT: $result = $fm -> getRecords ($parameters [,$layout]);

 

EXAMPLE:

$parameters ['_offset'] = 1;

$parameters ['_limit'] = 50;

$parameters ['script'] = 'my script name';

$parameters ['script.param'] = 'a parameter for that script';

$result = $fm -> getRecords ($parameters); 

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • scripts can be set to run during specific parts of each routine and other parameters can specify portal data returned and more. See API docs for more details.
  • please note the preceding underscore in some of the parameters (“_limit” for example) on this call, as specified in the API docs.

FIND RECORDS:

FORMAT: $result = $fm -> findRecords ($data [, $layout]);

 

EXAMPLE:

$request1['my_field_name'] = 'my_field_value';

$request1['another field'] =  'another value';

$request2['my_field_name'] = 'my_field_value';

$query = array ($request1, $request2);

$data['query'] = $query;

$data['limit'] = 2;

$data['script'] = 'find script';

$data['script.param'] = 'script parameter';

$result = $fm -> findRecords ($data); 

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • you can have any number of requests be part of a query by adding elements to the $query variable.
  • you can also add sort, offset, range and portal by adding these parameters to the $data variable.
  • please note how the request data is an array of fields, which is wrapped within another array (for each request), then wrapped into another array before it’s sent to the findRecords function.
  • all field data needs to be wrapped in quotation marks – even number fields
  • scripts can be set to run during specific parts of each routine. See API docs for more details.

UPLOAD CONTAINER:

FORMAT: $result = $fm -> uploadContainer ($recordId, $fieldName, $file [, $layout] );

 

EXAMPLE:

$recordId = 1234;

$fieldName = 'container';

$file = $_FILES['file'];

$result = $fm -> uploadContainer ($recordId, $fieldName, $file );

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’]

SET GLOBAL FIELDS:

FORMAT: $result = $fm -> setGlobalFields ($data);

 

EXAMPLE:

$globals['my toc::my field'] = 'my_field_value';

$globals['another toc::another field'] =  'another value';

$data['globalFields'] = $globals;

$result = $fm -> setGlobalFields ($data); 

notes:

  • please note how the field data is an array of fields, wrapped within another array
  • all field data needs to be wrapped in quotation marks – even number fields
  • the field name needs to be an absolute reference, including the table occurrence name

EXECUTE A SCRIPT:

FORMAT:  $result = $fm -> executeScript ($scriptname [,$scriptparameter, $layout]);

 

EXAMPLE:

$result = $fm -> executeScript ($_REQUEST['Script'],$_REQUEST['Parameter']);  

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • New for FileMaker 18

META DATA:

$result = $fm -> productInfo ();

$result = $fm -> databaseNames ();

$result = $fm -> layoutNames ();

$result = $fm -> scriptNames ();

$result = $fm -> layoutMetadata ([$layout]);

$result = $fm -> oldLayoutMetadata ([$layout]);

notes:

  • layout is optional if you’ve included a layout when you called “new fmREST()” function.
  • New for FileMaker 18

DEBUGGING:

You now have three options for showing the debug output of fmREST.php:

  1. $fm -> show_debug = true;  – turn on debugging when instantiating class –  will automatically show the debug output after your code has executed.
  2. $fm -> show_debug = “HTML”; – turn on debugging when instantiating class – will automatically show the debug output in HTML format instead of as an array.
  3. print_r ($fm -> debug_array); – manually output the contents of the debug array wherever you want it on your page, or use it elsewhere.

SECURITY AND OTHER NOTES:

fmREST automatically checks for a valid secure certificate. You can override this by setting the secure parameter to false like this: $fm -> secure = false;

You should also use a secure connection to your PHP page using “https://”. If you don’t, the cookies won’t be set, and you will see multiple tokens/connections on your FileMaker Server.

You can name your cookie whatever you’d like in your browser. By default it is named “fmtoken”. Change it like this: $fm -> token_name = “cookieName”;

To work with FileMaker 17 instead of FileMaker 18, change the following two settings:

$fm -> version = "v1";

$fm -> fmversion = 17;

LinkedInGoogle+Pinterest