By: Mark Walsh, Consultant, IT Solutions
Let's take a look at how the data API works. For the server, you can find the API endpoints (the URIs used for the API) for your server at https://yourserveradress/fmi/rest/apidoc. For the client, we'll use a tool called Postman. You can get Postman as an add-on app for Google Chrome from the Chrome Web Store.
To access FileMaker data from the Data API, you first need to obtain an Authentication Token. This is a string which represents your active session with FileMaker Server. All subsequent requests will use this ID in place of your credentials. Here, we query the "Auth" API endpoint, also specifying the "JerrCoHR" database. Notice that both the Request Body data (authentication information) and the Response Body data (session information) are in JSON format. Also notice the HTTP Status in the Response section. The "200 OK" is a standard HTTP response status and means that the API call was successful.
Once you have a session token, you can submit the token with the HTTP Request in the Headers section. Here, we query the "Record" API endpoint, specifying the "Personnel_Data" layout and retrieving the record with an ID of 2. This ID is FileMaker's internal record ID (also obtained in FIleMaker via the Get(RecordID) function), and not a field created by a developer (in this example, they happen to be the same). We receive back a response with various metadata including the FileMaker error code and any data returned. Although not displayed here, the Data API will return any related records from portals on the layout as part of the record data. Notice that container fields also come through from the API in the form of a URI, allowing applications to download documents or display pictures.
The Data API isn't read-only; we can also create new records. Here, we supply the session token in the header along with an additional header of "Content-Type" set to "application/json" (just like the initial login). We then supply the Request Body with a JSON object containing the data we want to add. The URI specifies the layout and context, and the Body specifies our field data.
Here, we use the URI to list available records; this is similar to the single-record URI we saw before, but returns all records from the table. We can see that our new record has been created and is found in the list of records returned, along with all the standard auto-entered data specified in the FileMaker schema.
Logging Out/Ending Session
When a client is finished, it can end the API session using the Logout method in the "Auth" API endpoint. The session token is supplied, and the method returns a response indicating the session has ended successfully.
Whether the client session is ended through the logout process or the session expires, attempting to access the API with the session token will result in an authentication error. To continue accessing the API, you'll need to log in again. Notice that when an API call results in error, we not only see it indicated in the Response Body, but we also get an appropriate HTTP error code as well. This can be useful in determining how to handle unexpected errors in your applications.
It's worth noting that the Data API also has some limitations. The Data API cannot activate script triggers or scripts, so ensure you're aware of any scripts running on the layouts you use that might affect data and relationships. The Data API also does not trigger "Data Entry" validation settings; however, it does respect "Always" validation settings. Be sure to consider this when designing your FileMaker schema or remote application. When "Always" validation isn't an option, you can use an Auto-enter calculation along with the "Self" context-dependent function to augment the data submitted before the data is committed.
These are just a few features of the new Data API available in FileMaker 16, but there are many other features available. Some of these include using the "Find" API endpoint to conduct searches and return a list of matching records, using the "Global" API endpoint to set global field values used in relationships and other FileMaker-specific functionality on which your data depends (this is especially helpful when replicating script trigger functionality). You could even use the new cURL support to query other FileMaker files from within a FileMaker database.
The new RESTful Data API can be a powerful tool. How will you use it in your next application?