The Insert from URL script step is the keystone for all API integrations; it is how you call an external API and get its response back.
At the core of this powerhouse script step, sits the cURL library with its rather arcane set of command-line switches to specify all the different options for putting the request together.
Tools like Postman and Insomnia help you construct the syntax by allowing you to build the request and then translate it into cURL.
But even with that translation, it remains difficult to remember what some of the options stand for and what the difference is, for instance, between -x and -X, especially if you don’t live and breathe cURL every day.
Moreover, FileMaker supports a subset of the available cURL options, so once in a while, these translation tools would use a cURL option that does not work in FileMaker or does not work in exactly the same way. For instance: FileMaker deliberately – for security reasons – disallows sending files that live on the hard disk of your computer. It only allows files that are in container fields or have been set to a variable.
And as you can see in Figure 1, tools like Postman (and many API documentation sites) use the backslash (\) character to indicate line continuation; that the syntax really is just one long line but broken up for readability. The backslash has a totally different meaning in FileMaker, however. It indicates that the next character should be escaped, taken literally. When you paste that syntax from Postman or the API documentation you have into FileMaker, then it may not work as you expect it to because of that difference in meaning.
Back when FileMaker 16 introduced the cURL options to the Insert from URL script step, we started building a library of custom functions to help us quickly pick from the supported cURL options and to keep the whole cURL options syntax readable.
Every version of FileMaker since then has added a few cURL options to the supported list. The new options in 19 are all about the ability to send an SSL certificate with your request. The full list of all supported options is in the online help. (Although at the time this blog was written, the online help was not yet updated with the changes for 19).
cURL Options Library
Our library has also been updated with the new cURL options. If you have never worked with the library, here’s a quick overview of how it works.
Copy over the custom functions into your solution. Yes, there are many, but they are named in such a way that they will not get in your way.
When you construct an Insert from URL call to an API, you may want to set a variable ahead of time with the cURL options that you need. This gives you a chance to inspect them when you are debugging. The extra line of code has no effect on FileMaker’s execution speed.
A simple example below; we are using the free “postb.in” service to test out a few mock API calls.
The URL to create a ‘bin’ is on line 28 and the cURL options are set on line 31. The call to the API is executed by the Insert from URL on line 32.
Line 31 is where we use our custom functions. As you can see, we can simply string together all the options we need without worrying about single or double quotes or any other string formatting issues.
And because these are functions, they are available in FileMaker’s type-ahead auto-complete: if you type in different parts of the name, you can quickly see and select the option you are after.
That significantly cuts down on any typos in the cURL syntax and takes the guesswork out of remembering which options are supported in FileMaker.
Similarly, the library contains custom functions to replace hard-to-remember general options such as the various RFC numbers for the Base64 Encoding function:
You will find custom functions that represent text encoding options, JSON data types, and encryption algorithms.
Specifically for FileMaker 19, creating an API call that requires you to send an SSL certificate along with the private key and the key passphrase is as simple as this, after having set variables $key and $cert with the content of the container field where you store the SSL certificate and the key files.
Which FileMaker will then translate into the proper cURL syntax for us:
We hope this library can make your development work easier; feel free to reach out to us with questions and ideas.