What is an API and why should you care? APIs are the means by which your FileMaker solution can access all kinds of services and interface with other data stores. When you get a little understanding of this, the world of systems integration really opens up for you.

API stands for Application Program Interface. It is the interface by which an application accesses a service. It essentially provides an interpreter service translating requests into language the service can understand and returns the results requested. It means that the service can be treated as a black box – requests go in, unseen magic happens, and results come out.

The Restaurant

An analogy may be useful. You are a customer (application) seated at a restaurant. You are hungry and would like to eat, so you peruse the menu and decide on a steak.

You can’t go into the kitchen and cook it yourself or direct the chef to cook it for you. Instead, a waiter (API) takes your order. He or she interprets your specific requirements such as wanting it cooked medium-rare and serving the sauce on the side. The waiter then communicates the order to the kitchen (service) in a manner understood by them. The kitchen staff prepare the meal and ring a bell when it is ready.

Neither you nor the waiter know how it was done. Your meal is delivered to your table as ordered.

The reverse can happen when it comes to pay for your meal – the restaurant becomes the application requesting a result (payment) from you.

API Services

In our case, we are interested in accessing external services from our FileMaker solution. This may be to simply push or pull data, or to manipulate data for us.

Examples of services we may use:

• send a text message by SMS
• submit invoice data to an accounting application
• retrieve the English version of some foreign language text
• submit an ISBN to get all the data about a book
• verify a credit card for processing

A lot of the services fit into the category of ‘not reinventing the wheel’ – it is far easier and more robust to access a service that is designed expressly for purpose, then to try to build and maintain it yourself.

Making an API Request

The basics of any API transaction are similar:

1. establish identity and authority to make a request
2. make the request providing data in the required format
3. receive a result

Sometimes the result is as simple as ‘OK’. Sometimes it is a stream of data.

Example – Sending an SMS

In this example, we will send an SMS text message from a FileMaker database to a given mobile (cell) number using a service called ClickSend. ClickSend have a number of APIs – the one we will be using is their REST API – by their description it is the “Latest most powerful API with JSON request and response.”

1. Authorisation

To use the API, you need to create a free account. This sets you up with an API username and API key. These are used to authenticate yourself to use the service. It also authorises the service to use credits in your account to send SMS messages.

My username is davidhead and my API Key is of the form 5AF333BF-0D51-617D-4586-A1B1188006XX (not my real key).

The Authorization header is constructed by combining username and password as a string – username:password. This is encoded using Base64 encoding and the authorisation method and a space is put before the encoded string. Using the above username and key, you will get:

Authorization: Basic ZGF2aWRoZWFkOjVBRjMzM0JGLTBENTEtNjE3RC00NTg2LUExQjExODgwMDZYWA==

Side Note: if you use the FileMaker function Base64Decode on the encoded text, you will see the original username and key separated by a colon.

2. Make the Request

The ClickSend API documents for “Send SMS” detail the structure of the request including what data is required and in what format.

The HTTP request is a POST – data is being sent to the service. Another common method is GET – to request data from a resource.

The content is supplied in JSON format. A single message has a number of possible properties:

• source – method of sending e.g. php
• from – the mobile number that will show as the sender
• body – the text message to be sent
• to – the mobile number of the recipient
• schedule – an optional time code to schedule sending of the message
• custom string – your reference for the message

In FileMaker Pro, the request is made with a script step Insert From URL. In that script step, we can specify the URL to call, any options to be sent with the call, and the target for the result (a field or a variable).

The URL we call is known as an endpoint. The API documents tell us the base URL and the endpoint for each service. For the current ClickSend API, the base URL is https://rest.clicksend.com/v3/ and the endpoint for the Send SMS service is sms/send. So the URL we will send to is https://rest.clicksend.com/v3/sms/send

The options sent with the request are cURL options. These are the request type (POST), an authorisation header (encoded in Base64 as above), a content header (saying the content is in JSON format), and the message properties structured in JSON.

3. Receive a Result

The result is received back into the target defined in the Insert from URL script step. This may be a field or a variable. For the ClickSend API, the result is returned in JSON format. It contains a copy of all the data supplied as well as sending information such as message_price (0.077), status (SUCCESS), http_code (200), and more.

The result can be parsed into a FileMaker record to save the result of the message send operation.

Conclusion

This has been a brief primer on the use of an API in your FileMaker solutions. In this article, we have only considered one example of an API request from FileMaker. FileMaker Server also provides a Data API. This can be accessed by external services to push data into and pull data from FileMaker solution hosted by FileMaker Server.

Can we help?

Do you need assistance finding an API or integrating it into your FileMaker solution? Or do you just want to discuss the range of possible options for accessing the myriad of API services out there? We are here and ready to help you. Contact us today.