FileMaker 17 Data API Guide
About the FileMaker Data API
Overview
The FileMaker® Data API is an application programming interface (API) that allows web services to access data in hosted databases. Because this API conforms to Representational State Transfer (REST) architecture, the FileMaker Data API is a REST API.
Your web service or application calls the FileMaker Data API to obtain an authentication token for access to a hosted database, then uses that token in subsequent calls to create records, update records, delete records, and perform find requests.
The FileMaker Data API returns data in JavaScript Object Notation (JSON), a text format that is commonly used with REST APIs because it is independent of specific programming language formats.
This guide assumes you are experienced with:
- using FileMaker Pro Advanced to create databases. You should understand the basics of FileMaker Pro Advanced database design and the concepts of fields, relationships, layouts, portals, and containers. See FileMaker Pro Advanced Help.
- using FileMaker Server to host databases. You should understand how to deploy FileMaker Server, enable access to hosted databases, and monitor hosted databases using FileMaker Server Admin Console. See FileMaker Server Help.
- using REST APIs in server-side applications or web services that call POST, GET, PATCH, and DELETE methods with data in JSON format. You can use any programming languages or tools you choose.
To use the FileMaker Data API, follow these steps:
- Prepare your database for FileMaker Data API access using FileMaker Pro Advanced. You can create a database or prepare an existing database. See Prepare databases for FileMaker Data API access.
- Write code that calls FileMaker Data API methods to find, create, edit, and delete records in a hosted database. See Write FileMaker Data API calls.
- Host your solution using FileMaker Server with FileMaker Data API access enabled. See Host a FileMaker Data API solution.
- Test that FileMaker Data API access is working correctly. See Test a FileMaker Data API solution.
- Monitor your hosted solution using Admin Console. See Monitor FileMaker Data API solutions.
How a FileMaker Data API call is processed
-
A REST API client sends a FileMaker Data API call (HTTPS request) to the FileMaker Server web server over the HTTPS port (port 443). FileMaker Pro Advanced does not need to be installed or running.
- The web server routes the request through the FileMaker Web Server Module to the FileMaker Data API Engine.
- The FileMaker Data API Engine converts the HTTPS request (URL and JSON data) into a format that the Database Server component can understand, and requests data from the database hosted by the Database Server.
- The Database Server sends the requested FileMaker data back to the FileMaker Data API Engine.
- The FileMaker Data API Engine converts the FileMaker data into an HTTPS response (URL with JSON data) to respond to the call, passing the data back to the web server.
- The web server sends the HTTPS response to the requesting REST API client.
The FileMaker Data API Engine requires that ports 3000 and 8989 be available.
The Database Server requires that port 5003 be available.
Web publishing alternatives
If you aren't experienced using REST APIs, consider the following alternatives to publish your FileMaker data on the Internet.
FileMaker WebDirect™: Web users connect to your database hosted on FileMaker Server to view, edit, sort, or search records if you give them access privileges. They don't need to install additional software—just compatible web browser software and access to the Internet or an intranet. The user interface resembles the desktop FileMaker Pro Advanced application. The webpages and forms that the web user interacts with are dependent on the layouts and views defined in the FileMaker Pro Advanced database.
See FileMaker WebDirect Guide.
Static publishing: If your data rarely changes, or if you don't want users to have a live connection to your database, you can use static publishing. With static publishing, you export FileMaker Pro Advanced data to create a webpage that you can further customize with HTML. The webpage doesn't change when information in your database changes, and users don't connect to your database.
See Publishing data on static webpages in FileMaker Pro Advanced Help.
Custom Web Publishing: To integrate your FileMaker database with a custom website, use the Custom Web Publishing technologies.
Prepare databases for FileMaker Data API access
Determine the data to access
You can create a FileMaker Pro Advanced database to use with the FileMaker Data API or use an existing database. If you are creating a database, you can design the layouts and fields that your FileMaker Data API solution requires. If you are using an existing database, consider creating a layout specifically for your FileMaker Data API solution.
FileMaker Data API calls that access record data require that you specify a layout. The FileMaker Data API uses the default view that is defined for the layout that you specify. Specify a layout that defines Form View as the default view for the layout. If you use a layout that defines Table View as the default view, the FileMaker Data API will not be able to get data from related records.
Protect your FileMaker Data API solutions
The FileMaker Data API requires your REST API code to log in to a database session using a password-protected account. Assign passwords to database accounts that are used for REST API access or use an OAuth service provider for those accounts.
Note:When defining account names and passwords for FileMaker Data API solutions, use printable ASCII characters, for example a-z, A-Z, and 0-9. For more secure account names and passwords, include punctuation characters such as "!" and "%," but do not include colons. See FileMaker Pro Advanced Help.
Enable FileMaker Data API access
You must enable the Access via FileMaker Data API extended privilege in each database you want to access using the FileMaker Data API. If you don't enable the FileMaker Data API extended privilege in the database, REST API applications won't be able to use the FileMaker Data API to access the database even if the database is hosted by FileMaker Server.
To enable FileMaker Data API access for a database:
- In FileMaker Pro Advanced, open the database using an account that has the Full Access privilege set. Alternatively, you can open the database using an account that has the Manage Extended Privileges access privileges.
- In the Extended Privileges tab of the Manage Security dialog box, select the fmrest extended privilege to enable it.
- Assign the privilege sets that include the fmrest extended privilege to one or more accounts.
Note:For security reasons, enable the fmrest extended privilege only in the privilege sets for accounts that you want to allow access to your hosted database.
See “Creating and editing privilege sets” in FileMaker Pro Advanced Help.
Design the FileMaker Data API solution
FileMaker Data API features
The FileMaker Data API provides a REST API to access data in hosted databases. The FileMaker Data API allows your code to:
- log in or log out of a hosted database. See Connect to or disconnect from a database.
- create, edit, delete, or get a record; or get a range of records. See Work with records.
- perform find requests. See Perform a find request.
- set global field values. See Set global field values.
- run FileMaker scripts. See FileMaker scripts and the FileMaker Data API.
- uploading data into container fields. See Upload container data.
- access data in external FileMaker tables. See Log in to an external data source.
- use a different layout for response data when getting a record or a range of records. See Get a single record, Get a range of records, and Perform a find request.
The FileMaker Data API does not support:
- access to data in external ODBC data sources.
- FileMaker plug-ins.
- script trigger activation through user interaction. A FileMaker Data API solution can activate script triggers only by running a FileMaker script.
- access to the server machine's file system. For example, the FileMaker Data API does not support the FileMaker Pro Advanced function Get(TemporaryPath). This function returns an empty string when used with the FileMaker Data API. Files can be stored in a container field, but there is no access to the server's file system.
The FileMaker Data API returns field data as it is stored in the database, not as it is displayed in FileMaker Pro Advanced.
FileMaker Data API reference information
When you installed FileMaker Server, you installed the FileMaker Data API reference files. This reference provides detailed information about all of the calls supported by the FileMaker Data API.
Note:To view the reference information, check that FileMaker Data API access has been enabled in Admin Console. See FileMaker Server Help.
- To view the reference in a browser window on the master machine, enter the URL
https://localhost/fmi/data/apidoc/
- To view the reference in a browser window on a remote machine, enter the URL
https://
host
/fmi/data/apidoc/
wherehost
is the IP address or host name of the master machine running FileMaker Server. On a Windows server, the reference files are in the folder
[drive]
:\Program Files\FileMaker\FileMaker Server\Documentation\Data API Documentation
where[drive]
is the drive on which your FileMaker Server deployment resides.If you install using a non-default location on Windows, your installation location replaces the beginning of the default installation path
[drive]
:[installation_location]
\FileMaker\FileMaker Server\Documentation\Data API Documentation- On a macOS server, the reference files are in the folder
/Library/FileMaker Server/Documentation/Data API Documentation
Notes
- The reference files show variables in the URLs by using a keyword preceded by a colon (:). For example:
:database
- This guide shows variables in the URLs by using an italic font. For example:
database-name
URL and data format notes
- There may be URLs or parts of URLs where text case doesn't matter, but in general, treat URLs as if they are case sensitive. For example, if you use a lowercase database name to log in to a database session, continue to use a lowercase database name for all subsequent URLs that pass the same session token. Otherwise, you may receive an invalid token error message.
- Strings in URLs must use URL encoding, also known as percent encoding, which is normal for HTTP requests. For example, to specify a layout name that includes a slash character, you must specify the slash character as the following encoded value: "%2F"
- String data values specified in parameters in the body of the request must use UTF-8 encoding.
- In general, the FileMaker Data API treats numeric data values as if they were in double-precision floating-point format (binary64). Use the corresponding data format in the programming language that you use. (Numeric data values should not be enclosed in quotation marks and should not use URL encoding.)
- Data values for number, date, time, and timestamp fields follow the same limits as specified by FileMaker Pro Advanced. See FileMaker Pro Advanced Help.
- The fields and portals that you specify must be on the layout that you specify.
- To specify related fields, use the
portalData
syntax.Note:The
tablename::related-field(repetition-number).record-id
syntax from the previous release is still supported, but theportalData
syntax is preferred. - For container field data, the FileMaker Data API returns a URL with the path reference to the container data object.
FileMaker scripts and the FileMaker Data API
FileMaker scripts can automate frequently performed tasks and can combine several tasks. When used with the FileMaker Data API, FileMaker scripts allow web services to perform more tasks or a series of tasks. See Running FileMaker scripts.
To see script steps that the FileMaker Data API supports, in the FileMaker Pro Advanced Script Workspace, click the Compatibility button and choose FileMaker Data API. Script steps that are not dimmed are supported for the FileMaker Data API. Some script steps perform differently in the FileMaker Data API than in FileMaker Pro Advanced. See FileMaker Pro Advanced Help.
Scripts run by the FileMaker Data API cannot run scripts in other FileMaker files unless the files are hosted on the same installation of FileMaker Server and unless the fmrest extended privilege is enabled in the other files.
In FileMaker Pro Advanced, both scripts and user actions (such as the user clicking a field) can activate script triggers. But in FileMaker Data API solutions, only scripts can activate script triggers. For information on script triggers, see FileMaker Pro Advanced Help.
Notes
- Consider the amount of data and the number of records a script may return, and define scripts accordingly. In FileMaker Pro Advanced, a script may return all the records from a table or from the current found set. But if a script returns all the records from a table, a web service may run out of memory trying to process the records.
- Use accounts and privileges to restrict the set of scripts that a web service can run. Verify that the scripts contain only web-compatible script steps, and provide access only to scripts that should be used from a web service.
- Consider the side effects of scripts that run a combination of steps that are controlled by access privileges. For example, if a script includes a step to delete records, and the web service does not log in with an account that allows record deletion, the script will not perform the Delete Records script step. However, the script might continue to run, which could lead to unexpected results.
- In the Script Workspace, grant full access privileges to a script to allow the script to perform tasks that you would not grant individuals access to. For example, you can prevent users from deleting records with their accounts and privileges, but allow them to run a script that would delete certain records under conditions defined in the script.
- Some scripts that need only one script step when run from a FileMaker Pro Advanced client may require an additional Commit Record/Request script step to save the data to the host when run in a FileMaker Data API solution. Because web services don't have a direct connection to the host, they aren't notified when data changes. For example, features like conditional value lists may not work as expected because the data must be saved to the host.
- Any script that modifies data should include the Commit Record/Request script step, because data changes aren't accessible until the data is saved to the server. This includes script steps like Cut, Copy, and Paste. Many single-step actions should be converted into scripts to include the Commit Record/Request step. When designing scripts that will be run from a web service, include the Commit Record/Request step at the end of a script to make sure all changes are saved.
- Open each script that web users might run, and verify that the script will run properly when the database is hosted as a FileMaker Data API solution. Check that the script uses only script steps that are supported by the FileMaker Data API, as described above.
Write FileMaker Data API calls
REST API call components
The FileMaker Data API calls consist of the following components.
Component | Description |
---|---|
An HTTP method (also known as an HTTP verb) |
The FileMaker Data API uses the following HTTP methods:
|
HTTP headers |
The FileMaker Data API uses the following headers:
|
A call URL | The FileMaker Data API URLs all start with one of the following:
|
Parameter data in JSON format | Not needed with Log out of a database session, Delete a record, Get a single record, or Get a range of records. |
Connect to or disconnect from a database
The FileMaker Data API uses an access token to define a connection to a database. That access token must be used in the header of all subsequent calls to the hosted database. The access token is valid until you log out of a database session or for 15 minutes after the last call that specified the token. (While the token is valid, each call that specifies the token resets the session timeout counter to zero.)
Log in to a database session
To log in to a hosted database, use an HTTP POST method with the
sessions
URL specifying the name of a hosted database.
The account name and password are specified in a header Authorization string.
If the account name and password are authenticated, your code receives an access token that defines your connection to the database.
This connection is called a database session.
HTTP method | POST |
---|---|
URL | /fmi/data/v1/databases/database-name/sessions database-name – the name of the hosted database |
HTTP header | Content-Type: application/json Authorization: a base64-encoded string representing the account name and password to use to log in to the hosted database. This base64-encoded string should follow the standard HTTP Basic Authentication Scheme. (The account name and password are separated by a colon.) |
Parameters |
An empty set of curly braces. For example:
May optionally use the |
Response | The access token, an empty response body, and a messages array showing an error code of 0. The X-FM-Data-Access-Token header is returned in response, which is the session token to be used for subsequent API calls. For example: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Log in to an external data source
If your hosted database needs to log in to an external data source,
the hosted database name is specified in the URL;
the account name and password for the hosted database are specified in a header Authorization string;
and the database name, account name, and password for the external data source are specified in
the fmDataSource
parameter as a JSON array.
HTTP method | POST |
---|---|
URL | /fmi/data/v1/databases/database-name/sessions database-name – the name of the hosted database |
HTTP header | Content-Type: application/json Authorization: a base64-encoded string representing the account name and password to use to log in to the hosted database. This base64-encoded string should follow the standard HTTP Basic Authentication Scheme. |
Parameters | The For example: { "fmDataSource":
[ { "database":"contacts", "username":"admin", "password":"admin" } ]
}
To use an OAuth account to log in to the external data source, specify the X-FMS-Request-ID header value ( { "fmDataSource":
[ { "database":"contacts", "oAuthRequestId": "E65B98BB17429CO643B31119F", "oAuthIdentifier": "B164A3459A776E5177445DR223"} ]
}
|
Response | The access token, an empty response body, and a messages array showing an error code of 0. The X-FM-Data-Access-Token header is returned in response, which is the session token to be used for subsequent API calls. For example: X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Note:FileMaker databases are the only external data sources supported. Specify the database name without the .fmp12 filename extension.
Log in to a database session using an OAuth identity provider
To log in to a hosted database using an OAuth identity provider, use an HTTP POST method with the sessions
URL specifying the database.
Use the X-FM-Data-OAuth-Request-Id string and X-FM-Data-OAuth-Identifier string in the header to authenticate access to the hosted database. If the authentication is accepted, your code receives an access token that defines your connection to the database.
This connection is called a database session.
HTTP method | POST |
---|---|
URL | /fmi/data/v1/databases/database-name/sessions database-name – the name of the hosted database |
HTTP header | Content-Type: application/json X-FM-Data-OAuth-Request-Id: request-id X-FM-Data-OAuth-Identifier: identifier-parameter |
Parameters |
An empty set of curly braces. For example: May optionally use the |
Response | The access token, an empty response body, and a messages array showing an error code of 0. The X-FM-Data-Access-Token header is returned in response, which is the session token to be used for subsequent API calls. For example: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
To get the OAuth parameters in JSON format:
-
Get the list of supported OAuth providers by using an HTTP GET method with this URL:
https://host/fmws/oauthproviderinfo
where host is the IP address or domain name of the master machine in your FileMaker Server deployment. The list is returned in JSON format.
- Select a supported OAuth provider, and get a tracking ID for your session.
-
Use an HTTP GET method with this URL:
http://host/oauth/getoauthurl?trackingID=tracking-ID&provider=OAuth-provider&address=127.0.0.1&X-FMS-OAuth-AuthType=2
where host is the IP address or domain name of the master machine in your FileMaker Server deployment, tracking-ID is the developer-generated tracking ID for your session, and OAuth-provider is the name of your selected OAuth provider.
The HTTP header for this request needs to include the following:
- X-FMS-Application-Type: 9
- X-FMS-Application-Version: 15
- X-FMS-Return-URL: http://127.0.0.1/
- Read the response header for the X-FMS-Request-ID data. This response header contains the OAuth request ID that you will use for the X-FM-Data-OAuth-Request-ID string in the header.
- Read the response header for the X-FMS-Return-URL data. Call the URL returned in this parameter to allow the user to authenticate with the OAuth provider.
- The "identifier" returned by the OAuth provider is the OAuth identifier parameter that you will use for the X-FM-Data-OAuth-Identifier string in the header.
See "Creating accounts that authenticate via an OAuth identity provider" in FileMaker Pro Advanced Help.
Log out of a database session
When your code is done accessing the hosted database,
use an HTTP DELETE method with the sessions
URL specifying the name of the hosted database and the access token for the session.
If your code does not log out of the database session,
the access token becomes invalid
when the FileMaker Data API session times out
15 minutes after the last call that specified the token.
HTTP method | DELETE |
---|---|
URL | /fmi/data/v1/databases/database-name/sessions/session-token database-name – the name of the hosted database session-token – the X-FM-Data-Access-Token for the database session |
HTTP header | Content-Type: application/json |
Parameters | None |
Response |
An empty response body, and a messages array showing an error code of 0. For example: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Work with records
Create a record
To create a record, use an HTTP POST method with the records
URL specifying the database name and the layout.
HTTP method | POST |
---|---|
URL | /fmi/data/v1/databases/database-name/layouts/layout-name/records database-name – the name of the hosted database |
HTTP header | Content-Type: application/json Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | Record data in JSON format containing field-and-value pairs that specify values for fields that are in the target layout. The data may specify related records or portals that are on the layout by using the portalData specification. A portal name can be either the object name shown in the Inspector in FileMaker Pro Advanced or the related table name. For example: {"fieldData":
{
"String Field": "value_1",
"Number Field": 99.99,
"repetitionField(1)" : "fieldValue"
}
}
Note:To create an empty record with default values for each field, specify an empty data object in JSON format as the parameter. For example: {"fieldData":
{
}
}
You can run FileMaker scripts as part of this request by including the |
Response |
The record ID of the record that was created, and a messages array showing an error code of 0. For example: {
"response": {"recordId":147},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Notes
- When you create records using the FileMaker Data API, field validation is enforced. If the data does not pass field validation, you will receive an error message and the record will not be created.
Edit a record
To edit a record, use an HTTP PATCH method with the records
URL specifying the
database name, layout, and record ID.
HTTP method | PATCH |
---|---|
URL | /fmi/data/v1/databases/database-name/layouts/layout-name/records/record-id database-name – the name of the hosted database |
HTTP header |
Content-Type: application/json Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | Record data in JSON format containing field-and-value pairs that you want to update. The data may specify related records or portals that are on the layout by using the portalData specification. A portal name can be either the object name shown in the Inspector in FileMaker Pro Advanced or the related table name.
Only the fields you specify are updated; other fields in the record are not changed.
If "{}" is provided as the Optional parameter: Modification ID ( For example: {
"fieldData":
{
"First Name": "Joe",
},
"portalData":
{
"JobsTable": [
{
"recordId": 70,
"modId": 4,
"Job::Name": "Contractor"
}
]
}
}
You can run FileMaker scripts as part of this request by including the |
Response |
An empty response body, and a messages array showing an error code of 0. For example: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Notes
- When you edit records using the FileMaker Data API, field validation is enforced. If the data does not pass field validation, you will receive an error message and the record will not be updated.
-
To delete a related record, use the
deleteRelated
syntax.For example:
"deleteRelated" : "Orders.3"
Only one related record can be deleted per edit record call.
Delete a record
To delete a record, use an HTTP DELETE method with the records
URL specifying the
database name, layout, and record ID.
HTTP method | DELETE |
---|---|
URL | /fmi/data/v1/databases/database-name/layouts/layout-name/records/record-id database-name – the name of the hosted database You can run FileMaker scripts as part of this request by including the |
HTTP header | Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | None. |
Response |
An empty response body, and a messages array showing an error code of 0. For example: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Get a single record
To get a record, use an HTTP GET method with the records
URL specifying the
database name, layout, and record ID.
You can also specify portal information to limit the number of related records that are returned.
HTTP method | GET |
---|---|
URL | Format 1:
/fmi/data/v1/databases/database-name/layouts/layout-name/records/record-id
database-name – the name of the hosted database For the portal keyword: The portal portion of the URL is optional. If the layout includes portals, specify the portal names for better performance. If the portal portion is omitted, the call will return all related records in all portals on the layout. For For If you want the response data in the context of a different layout, use the You can run FileMaker scripts as part of this request by including the |
HTTP header | Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | None |
Response |
The record data in JSON format and a messages array showing an error code of 0. For example: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
See Error responses. |
Notes
- To return data for specific portal rows, use
_offset.portal-name
and_limit.portal-name
, where portal-name is the name for the portal in the Inspector in FileMaker Pro Advanced. If you omit the offset and limit values for portal rows, the default for offset is 1 and the default limit for portal records is 50.
Get a range of records
To get a range of records, use an HTTP GET method with the records
URL specifying the
database name, the layout, and additional information to specify a starting record and the number of records.
Optionally, you can specify the sort order of the records.
You can also specify portal information to limit the number of related records that are returned.
HTTP method | GET |
---|---|
URL |
Format 1 (returns up to the first 100 records): database-name – the name of the hosted database For For For the For the portal keyword: The portal portion of the URL is optional. If the layout includes portals, you may want to specify the portal names for performance reasons. If the portal portion is omitted, the call will return all related records in all of the portals on the layout. For For If you want the response data in the context of a different layout, use the
You can run FileMaker scripts as part of this request by including the |
HTTP header | Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | None |
Response |
The record data in JSON format and a messages array showing an error code of 0. For example: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
See Error responses. |
Notes
- If you omit the offset and limit values, the default for offset is 1 and the default limit for records is 100:
_offset=1&_limit=100
- If you omit the sortOrder keyword, the default is
ascend
. For example,&_sort=[{ "fieldName": "recordId" }]
is treated as:&_sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }]
- To return data for specific portal rows, use
_offset.portal-name
and_limit.portal-name
, where portal-name is the name for the portal in the Inspector in FileMaker Pro Advanced. If you omit the offset and limit values for portal rows, the default for offset is 1 and the default limit for portal records is 50.
Upload container data
To upload container data, use an HTTP POST method with the
containers
URL specifying the database name, layout name, record ID, field name,
and a field repetition.
HTTP method | POST |
---|---|
URL | Format:
/fmi/data/v1/databases/database-name/layouts/layout-name/records/record-id/containers/field-name/field-repetition
|
HTTP header |
Content-Type: multipart/form-data Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | A multipart MIME data stream (Content-Type: multipart/form-data) where the container field object is defined as
a part with Use a library that supports specifying multipart/form-data. |
Response |
An empty response body, and a messages array showing an error code of 0. For example: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
See Error responses. |
Notes
- The container field must be a field in the table occurrence of the specified layout. It cannot be a container field in a related table.
- The FileMaker Data API allows all MIME types. The MIME types are not checked to restrict them to the types supported by FileMaker software or the web server.
- The FileMaker Data API caches the container field data to a cache folder on the master machine when it is being uploaded, but the cached data is deleted when the request completes.
Perform a find request
To perform a find request, use an HTTP POST method with the
_find
URL specifying the
database name and the layout,
and additional information to specify the query fields and criteria, sort order, starting record, and number of records.
You can also specify portal information to limit the number of related records that are returned.
HTTP method | POST |
---|---|
URL |
/fmi/data/v1/databases/database-name/layouts/layout-name/_find database-name – the name of the hosted database |
HTTP header |
Content-Type: application/json Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | A query in JSON format specifying the fields and find criteria. Optional parameters specifying omit requests, the sort order, starting record (offset), number of records (limit), and portals for limiting the number of related records that are returned. If you want the response data in the context of a different layout, use the For example: {
"query":[
{"Group": "=Surgeon"},
{"Work State" : "NY", "omit" : "true"}],
"sort":[
{"fieldName": "Work State","sortOrder": "ascend"},
{"fieldName": "First Name", "sortOrder": "ascend"} ]
}
Example with offset, limit, and portals: {
"query":[
{"Group": "=Surgeon"},
{"Work State" : "NY", "omit" : "true"}],
"portal": ["Portal1","Portal2"],
"limit": "10",
"offset": "1",
"offset.Portal1": "1",
"limit.Portal1": "5",
"layout.response": "Doctors"
}
You can run FileMaker scripts as part of this request by including the |
Response |
The record data in JSON format and a messages array showing an error code of 0. For example: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
See Error responses. |
Notes
- In a database that has many related records, querying and sorting portal records can be time consuming. To restrict the number of records and rows to display in a related set, specify the offset.portal-name and limit.portal-name parameters.
- You cannot specify global fields as find criteria. If you specify a global field with a find request, you receive an error message. Instead, set the global field value before the find request. See Set global field values.
Set global field values
To set the values for global fields, use an HTTP PATCH method with the globals
URL specifying the
database name.
HTTP method | PATCH |
---|---|
URL | /fmi/data/v1/databases/database-name/globals database-name – the name of the hosted database |
HTTP header |
Content-Type: application/json Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session |
Parameters | A JSON object with field-and-value pairs specifying the global fields to set. The global fields must be specified using fully qualified field names (table name::field name). For example: { "globalFields":
{
"baseTable::gCompany":"FileMaker",
"baseTable::gCode":"95054"
}
}
|
Response |
An empty response body, and a messages array showing an error code of 0. For example: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
|
Running FileMaker scripts
Parameter | Value |
---|---|
script
|
The name of the script to be run after the action specified by the API call (get, create, edit, delete, find) and after the subsequent sort. |
script.param
|
The text string to use as a parameter for the script that was named by script .
|
script.prerequest
|
The name of the script to be run before the action specified by the API call and the subsequent sort. |
script.prerequest.param
|
The text string to use as a parameter for the script that was named by script.prerequest .
|
script.presort
|
The name of the script to be run after the action specified by the API call but before the subsequent sort. |
script.presort.param
|
The text string to use as a parameter for the script that was named by script.presort .
|
Script execution order
You can specify the script.prerequest
, script.presort
, and script
parameters on a single API call.
Each keyword can be specified only once.
FileMaker Server processes these parameters as part of the API call in this order:
- Go to the layout specified in the URL.
- Perform the script named by
script.prerequest
, if specified. - Perform the action specified by the API call (get, create, edit, delete, find).
- Perform the script named by
script.presort
, if specified. - Perform the sort specified on the API call:
- For Get a range of records, perform the sort specified by the
_sort
parameter. - For Perform a find request, perform the sort specified by the
sort
parameter.
- For Get a range of records, perform the sort specified by the
- Perform the script named by
script
, if specified. - Return the result set for the API call, with the offset and limit parameters applied, if specified.
Notes
- For calls that use HTTP GET and HTTP DELETE methods, the scripting parameters are included as URL parameters; see Get a single record, Get a range of records, and Delete a record.
- For calls that use HTTP POST and HTTP PATCH methods, the scripting parameters are included in the request body; see Create a record, Edit a record, and Perform a find request.
- For the script parameters
script.param
,script.prerequest.param
, andscript.presort.param
, you may specify only a single text string. To pass in multiple parameters, you can create a string delimiting the parameters and have your script parse out the individual parameters. For example, pass "param1|param2|param3" as a list with the "|" character URL-encoded as:param1%7Cparam2%7Cparam3
For example:
https://<host>/fmi/data/v1/databases/customers/layouts/entry/records/14?script=UpdateProcessing&script.param=14
For example:
{"query":[{"Title":"Office Manager"}], "script.prerequest":"Eliminate duplicates"}
Error responses
When an error occurs, the FileMaker Data API returns:
- an HTTP 400-level status code for standard HTTP errors
- an HTTP 500 status code for FileMaker Server errors
HTTP status code | HTTP category | Description |
---|---|---|
400 | Bad request | Occurs when the server cannot process the request due to a client error. |
401 | Unauthorized | Occurs when the client is not authorized to access the API. If this error occurs when attempting to log in to a database session, then there is a problem with the specified user account or password. If this error occurs with other calls, the access token is not specified or it is not valid. |
403 | Forbidden | Occurs when the client is authorized, but the call attempts an action that is forbidden for a different reason. |
404 | Not found | Occurs if the call uses a URL with an invalid URL schema. Check the specified URL for syntax errors. |
405 | Method not allowed | Occurs when an incorrect HTTP method is used with a call. |
415 | Unsupported media type | Occurs if the required header is missing or is not correct for the request:
|
500 | FileMaker Server error | Includes FileMaker error messages and error codes. See FileMaker error codes in FileMaker Pro Advanced Help. |
Notes
- If the FileMaker Data API Engine is not running or cannot be reached, then error codes or messages returned are dependent on your web server (Apache or IIS).
- For information about additional HTTP status codes returned, see www.w3.org.
Host, test, and monitor FileMaker Data API solutions
Host a FileMaker Data API solution
- Complete all of the steps in Prepare databases for FileMaker Data API access.
- Check that FileMaker Data API access has been enabled and properly configured in Admin Console. See FileMaker Server Help.
- Verify that the web server and the FileMaker Data API Engine are running.
-
Use encryption for communication.
The FileMaker Data API requires your REST API applications to use an HTTPS connection. HTTPS connections use Secure Sockets Layer (SSL) encryption for communication.
FileMaker Server provides a standard SSL certificate signed by FileMaker, Inc., that does not verify the server name. The FileMaker default certificate is intended only for test purposes. A custom SSL certificate is required for production use. See FileMaker Server Installation and Configuration Guide.
The language or technology that you use to call the FileMaker Data API must support Transport Layer Security (TLS) v1.2 to communicate with the web server.
Test a FileMaker Data API solution
Before putting your FileMaker Data API solution in production, verify that it functions as you expect.
- Test features like finding, adding, and deleting records with different accounts and privilege sets.
- Verify that privilege sets are performing as expected by testing with different accounts. Make sure unauthorized users can't access or modify your data.
- Test that your solution behaves the same when invoked from different operating systems.
Monitor FileMaker Data API solutions
The server administrator can use Admin Console to start or stop the FileMaker Data API Engine, monitor FileMaker Data API clients, track FileMaker Data API call use, and download the FileMaker Data API log file.
To | Use |
---|---|
Start or stop the FileMaker Data API Engine | The Admin Console Connectors > FileMaker Data API tab or a CLI command. See "Starting or stopping FileMaker Server components" in FileMaker Server Help. |
Monitor FileMaker Data API clients | The clients list on the Admin Console Databases page. This page shows details about the clients and about the databases being accessed. See "Administering clients" in FileMaker Server Help. From this page, you can disconnect FileMaker Data API clients, but you cannot send messages to them. |
Track FileMaker Data API call use | The Admin Console Connectors > FileMaker Data API tab. This tab displays the FileMaker Data API annual limit set by your FileMaker Server license, how much data has been transmitted so far in this license period, and the renewal date for your license. If you are approaching the annual limit, you can increase the limit using the Admin Console Administration > FileMaker Licenses tab. See "FileMaker Data API settings" in FileMaker Server Help. |
View the FileMaker Data API log |
While FileMaker Data API clients are connected to a database, statistical data about the clients is logged to the fmdapi.log. See "FileMaker Data API log" in FileMaker Server Help. |
FileMaker Data API integration with Tableau
About integration with Tableau
FileMaker Server includes the Tableau Web Data Connector, a sample implementation that accepts REST API calls in JSON format. Use the Tableau Web Data Connector to define a connection between FileMaker Server and Tableau Desktop. The connection uses the FileMaker Data API to import data from hosted FileMaker databases into Tableau Desktop.
Requirements for the Tableau Web Data Connector
- Tableau Desktop, minimum version 10, for Windows or macOS.
- A password-protected FileMaker Pro Advanced database containing the data to import. The database must be hosted on FileMaker Server.
-
A valid REST API endpoint. For FileMaker Server, the endpoint is an HTML connection point that provides information needed for web services. The endpoint has the format
https://<hostname>/fmi/data/v1/tableau/fm_connector.html
wherehostname
is the fully qualified host name of your FileMaker Server.For example:
https://myserver.mycompany.com/fmi/data/v1/tableau/fm_connector.html
A valid custom SSL certificate on FileMaker Server. The Tableau Web Data Connector will not allow importing data from FileMaker Server without a valid custom SSL certificate. If your server requires an intermediate certificate, the certificate must be installed on the server where FileMaker Server is deployed. Restart the server machine after making changes to the installed certificate before connecting with Tableau.
Note:If your server uses a subject alternative name (SAN) certificate, the hostname must match the common name used in the SAN certificate.
Prepare to import data into Tableau
Follow the steps in Prepare databases for FileMaker Data API access to define the layout for importing and to enable the database for FileMaker Data API access.
Note:To import data into Tableau, the table must have at least one record with record data.
The following FileMaker field types are imported as Tableau data types.
FileMaker field type | Tableau data type |
---|---|
text | string |
date | date |
time | string |
timestamp | datetime |
number | float |
The following FileMaker field types are not supported when importing into Tableau:
- container fields
- summary fields. You can create a summary field in Tableau based on data that you import from FileMaker.
- calculation fields. You can create a calculation field in Tableau based on data that you import from FileMaker.
- chart data
- data from FileMaker Pro Advanced portals. To import data from related records, create a FileMaker Pro Advanced layout based on the related table, or import data from separate FileMaker Pro Advanced tables into Tableau and then join the tables in Tableau.
- field repetitions where the display of repeating fields for Show repetitions includes multiple values. A single repetition is supported.
- non-numeric values in number fields. If Tableau finds non-numeric values in number fields, the data will not be imported.
Do not use reserved words as field names in FileMaker Pro Advanced.
Set up the data connection in Tableau Desktop
- In Tableau Desktop, under Connect (at the left side of the screen), choose More > Web Data Connector.
- Enter the URL for your FileMaker Server endpoint
https://<hostname>/fmi/data/v1/tableau/fm_connector.html
where<hostname>
is the fully qualified host name of your FileMaker Server. -
In the Import Data from FileMaker File dialog box:
-
Sign in to the FileMaker Pro Advanced database by entering the following information or by using an OAuth identity provider.
- Source Database Name: the name of the FileMaker Pro Advanced database
- Source Layout Name: the name of the FileMaker Pro Advanced layout
- Account Name: the name of the FileMaker Pro Advanced account with the fmrest privilege
- Password: the password for the FileMaker Pro Advanced account
- Select Enable incremental refresh to enable incremental refresh.
-
- Click Import FileMaker Data.
Tableau imports the data. The processing time depends on the number of records imported, server load, and network throughput. Tableau maps FileMaker Pro Advanced field names and data to dimensions and measures. String data is typically mapped to dimensions, while numeric data is typically mapped to measures. The mapping occurs automatically during import, but you can customize it.
Notes
-
When specifying the Source Layout Name, make sure the layout name is unique. If your database has two layouts with the same name, the Tableau data connection cannot distinguish between them. Tableau displays only one name, and it may not be the layout you wanted.
-
Use Enable incremental refresh to import only the new records.
- After importing FileMaker data with incremental refresh enabled, select the Sheet tab in Tableau to go to the worksheet.
- Choose Data > FM: database-name / layout-name > Extract > Refresh (Incremental).
- Select the Data Source tab.
- Click Update Now to display the new records.
- Enabling incremental refresh does not create an ongoing, live connection between Tableau and the hosted FileMaker database. You must run the incremental refresh manually.
- Incremental refresh imports only the new records. FileMaker Pro Advanced records that have been modified or deleted are not updated. To get modified data or to remove deleted records, you must create a new workbook in Tableau and reimport the data.
- Incremental refresh creates a field named -recordId. If you make changes to this field, you may be unable to perform an incremental refresh.
- In Tableau, you can change the schema and data that has been imported. But if you modify the schema or data in Tableau, those changes are not transmitted back to the FileMaker Pro Advanced file.
- If you change the schema in the FileMaker Pro Advanced file, you must create a new workbook in Tableau and reimport the data.
- Tableau Desktop database can be hosted on Tableau Server for Windows.
- If you close the Tableau workbook and reopen it, incremental import no longer works.
- After the data connection is established to Tableau, the FileMaker Web Data Connector caches the user account and password until the workbook is closed, with the following considerations:
- If the FileMaker session times out while you are connected to Tableau, the FileMaker Web Data Connector tries to reconnect the user to FileMaker Server.
- If the Tableau connection expires, the FileMaker Web Data Connector tries to reconnect to FileMaker Server as long as the Tableau workbook is open.
- If the workbook is closed and then reopened, you must enter your account name and password again during the initial data import.
- The Tableau Data Source page displays up to 1,000,000 (one million) rows, even if more records are imported.