Enabling the REST API

The first thing you need to do is to enable the API in FileMaker 16 Server's admin console. You will also need to enable the new fmrest extended privilege set in the security settings in your FileMaker file. All the same rules that apply to XML and the PHP API apply here: all calls must specify a layout, and only the fields and portals available on the layout will be available to the REST API.

Authentication

Authenticating with a FileMaker database through the REST API can be done in 2 different ways: using the standard username and password credentials you normally access the file with or using OAuth. For simplicity's sake, we'll be focusing on authenticating just using our standard FileMaker username and password. To do so you will need to send a POST request with the following settings and parameters.

Request Format:  POST ipaddress/fmi/rest/api/auth/:solution
Request Example: POST https://localhost/fmi/rest/api/auth/FM_QUICKSTART_v3
Headers: Content-Type: application/json
Body: {"user":"admin","password":"admin","layout":"Contact"}
Response:
{
  "errorCode": "0"
  "layout": "Contact",
  "token": "e86d7d4f4fa602ccb5a6b498a6634576b2da1b3efc67a7d907"
}

Once we have the token, we can use that to authenticate the rest of our API calls until it expires.

Viewing Data

To access the actual data from our FileMaker file, we'll make use of the "Get Records" and "Get Record" API methods. To get a list of records from FileMaker you need at a minimum to specify the file you want to access, the layout, and the token generated in the previous step. There are also a number of more advanced parameters you can include to adjust the range, offset, sort, and even what portals to include in the results.

Request Format:  GET ipaddress/fmi/rest/api/record/:solution/:layout
Request Example: GET https://localhost/fmi/rest/api/find/FM_QUICKSTART_v3/ContactWeb
Headers: FM-Data-token: e86d7d4f4fa602ccb5a6b498a6634576b2da1b3efc67a7d907
Response:
{
  "errorCode": "0",
  "result": "OK",
  "data": [
    {
      "fieldData": {
        "firstName": "Clark",
        "lastName": "Kent",
        "company": "DC",
        "isActive": "1",
        "picture": "https://localhost/Streaming_SSL/MainDB/0958204726F9842D89B1CD71DE2FB7CC.bmp?SessionKey=0958204726F9842D89B1CD71DE2FB7CC&RCType=EmbeddedRCFileProcessor"
      },
      "portalData": {
        "PORTAL:Address1": [],
        "PORTAL:Quotes": [],
        "NotesPortal": []
      },
      "recordId": "40",
      "modId": "9"
    },
    {
      "fieldData": {
        "firstName": "Peter",
        "lastName": "Parker",
        "company": "Marvel",
        "isActive": "1",
        "picture": "https://localhost/Streaming_SSL/MainDB/CDD151DF736F445D002D95A0FAE4F160.bmp?SessionKey=CDD151DF736F445D002D95A0FAE4F160&RCType=EmbeddedRCFileProcessor"
      },
      "portalData": {
        "PORTAL:Address1": [],
        "PORTAL:Quotes": [],
        "NotesPortal": []
      },
      "recordId": "44",
      "modId": "5"
    }
  ]
}

And if you only wanted one record you'd include the recordId like so.

GET ipaddress/fmi/rest/api/record/:solution/:layout/:recordId

Creating and Editing Records

Creating and editing records via the REST API are very similar, the only differences being the method, POST vs PUT and including a recordId when editing. Below is a sample for how you would create a new record.

Request Format:  POST ipaddress/fmi/rest/api/record/:solution/:layout
Request Example:  POST https://localhost/fmi/rest/api/record/FM_QUICKSTART_v3/ContactWeb
Headers: FM-Data-token: e86d7d4f4fa602ccb5a6b498a6634576b2da1b3efc67a7d907
Headers: Content-Type: application/json
Body:
{
"data": {
    "firstName": "Joe",
    "lastName" : "Bob",
    "isActive" : "1",
    "company" : "New Company"
     }
 }
Response:
{
  "errorCode": "0",
  "result": "OK",
  "recordId": "74"
}

And if you then wanted to update that record you would do the following.

Request Format:  PUT ipaddress/fmi/rest/api/record/:solution/:layout/:id
Request Example: PUT https://localhost/fmi/rest/api/find/FM_QUICKSTART_v3/ContactWeb/74
Headers: FM-Data-token: e86d7d4f4fa602ccb5a6b498a6634576b2da1b3efc67a7d907
Headers: Content-Type: application/json
Body:
{
"data": {
    "firstName": "Joey",
    "lastName" : "Bob",
    "isActive" : "0",
    "company" : "Other Company"
     }
 }
Response:
{
  "errorCode": "0",
  "result": "OK"
}

Deleting Records

The last API call I want to go over is how to delete a record. Deleting a record is very similar to viewing a single record, the only difference is the HTTP method you would use is the delete method. Here is an example of how to delete a record.

Request Format:  DELETE ipaddress/fmi/rest/api/record/:solution/:layout/:id
Request Example:  DELETE ipaddress/fmi/rest/api/record/FM_QUICKSTART_v3/ContactWeb/34
Headers: FM-Data-token: e86d7d4f4fa602ccb5a6b498a6634576b2da1b3efc67a7d907
Response:
{
  "errorCode": "0",
  "result": "OK"
}

Notes

Currently, there is no way to run a FileMaker script or get the contents of a value list like you can do using the XML or PHP API's. One thing that the new REST API does much better than previous CWP options is how it handles container fields, basically, it just works. There is no complicated container-bridge file to determine the mime type or anything like that, just a simple URL where you can view or download the item in the container.

Another thing you might run into while working with the API is that it does not return the number of records found when doing a find or accessing all records for a layout. This doesn't sound like a big deal, but without knowing the total number of records found you can't paginate your results reliably. Luckily there is a workaround for this. You'll need to create a new unstored calculation that calculates as "get( foundCount)" and put it on the layout you are using for your web call. The correct found count will be returned for every record, even if you are only pulling the first few records.

Conclusion

There's a lot to like with the new FileMaker REST API and we're excited to start using it in our web development. REST allows other technologies to integrate with your FileMaker solution that aren't well suited to the XML or PHP APIs. REST APIs are quickly becoming the number one way to interact with outside programs and services; you can view our article specifically about REST APIs for more info on what a REST API is. If you'd like assistance using REST APIs to integrate web solutions with FileMaker, please contact us today.