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.
Fantastic. This will save me a lot of time.
Hi, Thanks for this, but still struggling to get it to work.
I’m trying to connect FileMaker to Xero. Have successfully authenticated in Postman, but can’t replicate the same code in Filemaker.
The response I get is {“error”:”invalid_client”} which seems to refer to the authorisation value being incorrect, but I’m using the same value as in Postman.
Therefore it must be something to do with the syntax?
I’m combining these two fields and putting them into insert from URL
URL “https://identity.xero.com/connect/token”
CR. “–location –request POST
–header \”Content-Type: application/x-www-form-urlencoded\”
–header \”Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXkXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXcXXXXXXXXXXX\”
–data-urlencode \”grant_type=client_credentials\”
–data-urlencode \”scope=accounting.contacts accounting.transactions\” -D $header
”
Equivalent Postman script:
curl –location –request POST ‘https://identity.xero.com/connect/token’ \
–header ‘Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXkXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXcXXXXXXXXXXX’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘grant_type=client_credentials’ \
–data-urlencode ‘scope=accounting.contacts accounting.transactions’
According to their documentation, you will get that error when the client id and secret as encoded are not correct: https://developer.xero.com/documentation/guides/oauth2/troubleshooting
Since you’re getting a meaningful response, the connections actually works. Are you doing the Base64encoding in FM? If so make sure to pick an RFC that doesn’t include line breaks.
Thanks for the reply.
I’ve manually pasted the encoded client id and secret that was created in the Postman file into the Filemaker Code.
I have used an expression to create the encoded version in Filemaker as well, and they are both the same.
In that case I would capture the trace output and open a support ticket with Xero.
Thanks. Xero don’t offer API support, but I’ll try Filemaker. I dno’t mind paying for someone to fix it, but I can’t imagine I’m that far away!
I did find on the trace that the curl parser you’d kindly made didn’t parse the –data-urlencode elements correctly, although changing this didn’t fix the problem!
FYI, the original parse from the app gave this:
\” –data-urlencode \”grant_type=client_credentials\” –data-urlencode \”scope=accounting.contacts\”
which showed this in the trace:
(Filemaker) \”grant_type=client_credentials%5C%22&\”scope=accounting.contacts
(Terminal) grant_type=client_credentials&scope=accounting.contacts
Putting this into the Filemaker curl field :
–data-urlencode grant_type=client_credentials –data-urlencode scope=accounting.contacts
gave the same trace as Postman/ Terminal:
(Filemaker) grant_type=client_credentials&scope=accounting.contacts
(Terminal) grant_type=client_credentials&scope=accounting.contacts
In the “insert from URL” script step, disable the “automatically encode URL”
thanks, but I had done that
The only difference I can find in when comparing the traces, is that Terminal uses h2, whereas Filemaker uses http/1 then does a Chipher Selection
That should be easy enough to prove or disprove. Not sure about Postman but in Insomnia you can force the connection to use http/1. If that still works then that is not the issue.
Usually a protocol error would not let you connect at all. In your case the connection does work and the error is explicitly about the authentication header value.
Thanks, I think you’re correct.
I’ve actually found from the trace it’s not posting the encoded user credentials.
It works in Insomnia using http/1, so that’s not the issue, thanks.
I’ve got it working, your suggestion to try http/1 in Insomnia made me realise that wasn’t the issue, so thanks for that.
It was a syntax error after all.
It seems the cURL header values in FileMaker do need to be in quotation marks if there is a space eg. –header “authorization: basic XXXXXXX” works.
but both of these work:
–header Content-Type:application/x-www-form-urlencoded
–header “Content-Type:application/x-www-form-urlencoded”