Getting Started with FileMaker and REST

Representational State Transfer (REST) defines a set of standards and principals commonly used to provide web and application developers an Application Programming Interface (API). Built atop the HyperText Transfer Protocol (HTTP), REST is commonly used for viewing web pages. You are currently reading this blog post using HTTP.

FileMaker and REST

In every HTTP request, there is a specified method. If you type in a URL and press enter, the Method used is GET. If you submit a form on the web, you most likely use the POST Method. The difference is that a POST request can include a payload that is not part of the URL.

GET requests, if they include data, will include a question mark at the end of a URL and path. This is followed by data that usually appears in key-value pairs. RESTful services may or may not use key-value pairs and instead include all needed data in the URL path. Usually, data is transferred in XML or JSON as part of a POST payload in the HTTP request.

In general, following REST methodology, a GET request is used to read data, whereas a POST request is used to create a resource. These correlate to database interaction known as CRUD, or Create, Read, Update, and Delete. Modern versions of HTTP also support PUT and DELETE methods, which REST then commonly translates to Update and Delete database operations. PUT and DELETE are functionally identical to POST requests, the only difference being that the method specified is different.

This also includes encrypted in-transit information if you are using SSL and specify “https” in your URL.

FilerMaker “Insert from URL” Script Step

With me so far? Good. So how does FileMaker work with RESTful APIs and web services? With FileMaker 16, there was a lot of changes to the Insert from URL script step that allows you to use cURL functions. This also works across the entire FileMaker platform, so this includes server-side scripts as well as WebDirect and FM Go.

Anatomy of the script step:

The script step is configurable with several options. You can specify a Target, which can either be a field or a variable (see Figure 2). To specify a variable, select that option and give the variable a name you can reference it with, so you can use it later. Whether you use a global variable or not depends on where you need to use it.

Then specify the URL, which is the base URL and usually the complete path to the resource you are working with.

Specify cURL Options

Then there are the cURL options, which give you access to an entire library of functions for handling web requests. FileMaker supports quite a bit, but not all, cURL functionality. I recommend checking that documentation.

There are a couple points of interest when working with cURL options in FileMaker, specifically. The syntax for specifying variables can be confusing. You create a variable like you normally would, with a single or double dollar sign. However, when specifying the calculation to result in your desired cURL options, the variable name is INSIDE the quote marks, like so:

"--data @$myVariable"

This makes more sense if you are familiar with using the curl application with command line in a terminal window. For example, to upload a file with a command line, you use the atmark (@) and then the path to the file you want to include. Similarly, an atmark tells the cURL options in FileMaker where the variable you want to include resides. Referencing variables this way will also take care of any needed quoting, so your data does not break during transit.

When you send any kind of payload in the HTTP body using “–data” or “-d”, then POST is used by default as the method. If you need another method, you can specify it with the “–request” or “-X” flag in your cURL options.

Another point of note: using the “-D” or “–dump-header” option that allows you to get any returned HTTP headers and store them in a variable. This is especially important, as many RESTful services will return error codes as part of the HTTP header returned.

By the way, most cURL options are specified with flags, like “-D” above, but most also have the option to use a more verbose variant, which can be more readable, like “–dump-header”. They both work the same.

One more…since most RESTful services expect the payload to be JSON, you will also want to specify that as an HTTP header, like so:

" --header "Content-Type: application/json""

If the payload is XML, for example, you would change the content-type to match what you are sending, like text/xml. This will depend on the web service you are integrating with.

Troubleshooting “Insert from URL” Scripts

Trying to debug and troubleshoot when working with Insert from URL results can present challenges. It’s a little like working blind, where you construct a request and send it off without seeing how the request is being received on the other side. There are a couple websites that allow you to create endpoints that log requests and then view them. In my experience, however, they can be unreliable or slow.

To that end, I have written my own debugging tool that helps return information about requests sent with FileMaker. You can use it for free and put it on any web server that can serve PHP:

If you already have FileMaker Server, you can simply enable the web server with PHP and use it from there.

Once hosted, simply point your Insert from URL script to that PHP scripts URL and test any cURL options you need. Results are returned in plain text instead of HTML, since you would view the output in a FileMaker field or variable anyway.

Other Factors Concerning FileMaker and REST

You can encounter a host of other factors involved when working with APIs and web services. Those can include oAuth or information in your HTTP headers, such as signed requests or size information. It all depends on the service with which you integrate. This guide should help you start with the basics.

If you have questions about REST or other FileMaker web services, contact our team. We can help you choose the best options for your solution and leverage them directly within FileMaker for you.

Resources

• REST (Representational state transfer)
• CRUD (Create, read, update and delete)
• Available cURL options in FileMaker