With the release of FileMaker 16 came the Data API, a new RESTful API method to connect with FileMaker apps through the FileMaker Server. In FileMaker 17 features an updated Data API and welcomes a younger sibling, the Admin API. First, a few words about REST.
REST and FileMaker
REST, or Representational State Transfer, is a set of standards commonly used for developers to connect to applications via HTTP and HTTPS. It communicates from clients to server using base URLs, often with additional information depending on the requests made to the server.
In web pages, there are generally two HTTP methods to send data — GET and POST. (In fact, there are other methods as well, but these are the most common methods.) For POST (and some other methods), you send the information as options in a command called cURL. While not every POST method requires a payload in the body or data, the header options may require a variety of values. For example, sending a message needs to include the message in the data tag as JSON, while the Logout method and Duplicate Schedule method includes no payload in the data. In these latter cases you’ll usually be required to set the Content-Length to zero (0) in your cURL options. (Interestingly, the message parameter is listed as “optional” when send a message.)
The GET method supplies all information in the URL, while POST methods usually are built from forms. In the same sense, REST APIs use these two methods (as well as others). Since GET includes all information in the URL, developers can build their request as a URL and send this to a REST API that accepts this method. As we’ll see below, cURL options are where you specify header and data. The Admin API document specifies what you need to include in either the header or data tags as your cURL options.
Sending REST Commands from FileMaker
To send REST commands from FileMaker, we use the script step called “Insert from URL.” See Figure 1.
- Target refers to the field or variable to store the result of the Insert step.
- Specify URL is the url of the web service.
- Specify cURL options if where you set any header information and include the body or payload if there is one, the actual data that you want to send.
See Mike Duncan’s post, “Getting Started with FileMaker and REST” for more details on how to use the “Insert from URL” script, including how to set headers for cURL.
REST services return data in certain formats. One of the most common formats is JSON, the format returned by FileMaker’s Admin API.
The Admin API
While the Data API allows developers to communicate with data in FileMaker apps, the Admin API allows developers to communicate with the FileMaker Server. Prior to FileMaker 17 — indeed, from FileMaker Server 7 through FileMaker Server 16 — administrators had two ways to manage server settings: the Admin Console and the Command Line Interface.
Admin Console
The Admin Console is a web interface that works in browsers, with a modern user interface using point and click actions. The Command Line Interface is a set of commands typed into a Terminal application, generally while logged directly on the server itself.
With the Admin API, server admins now can access information about their server remotely using custom-made applications that work with REST. It’s even possible to set up admin apps in FileMaker Pro to manage server settings using the Insert from URL command.
Admin API Command Documentation
https://{{host}}:16000/fmi/admin/apidoc/
There are nearly 40 endpoints documented in this initial version of the Admin API. An endpoint is the URL where your web service can be accessed by a client applications. The same web service can have multiple endpoints.The endpoints may use different methods, including GET and POST, but also PUT and PATCH. Each method is defined in the API documentation.
Authentication
You need to authenticate once with your admin credentials to log in to the server for an Admin API session. These are the credentials you set up when you installed Server 17 and the same credentials in the admin console and command line interface. However, you authenticate with these credentials once, when you run the command to log in. After logging in, the Admin API returns an authentication token, which you include in subsequent commands.
https://{{host}}
This base URL is then followed by different endpoints, and often some additional headers set through a tool like cURL. The Admin API documentation lists these endpoints and instructions if you need to add information in the header or body of the request.
Testing the Admin API
There are various ways to test the Admin API. A free application called Postman lets you build collections of calls to API. You can send the information from Postman and receive information back (see Figure 2), whether your request was successful or failed for lack of access or some information.
Login
Your first action is to log into the server. The command for this is the first item of order in the documentation. Without this, all subsequent actions will fail.
https://{{server-name}}/fmi/admin/api/v1/user/login
The screenshot of the Postman interface above shows the URL and the Content-Type in the header. In the Body section, not shown here, is a JSON object with the username and password to your admin console. The Login command uses the POST method. The command also requires additional information sent along with the URL.
The header will include the request type, along with your username and password. In cURL the combined headers and body would look like this:
-X POST -H "Content-Type: application/json" -d { {"username":"MY_USERNAME", "password":"MY_PASSWORD"}
}Each “-letter” refers to a cURL option. You can find FileMaker’s list of supported options in the help documentation.
The above request refers to three options and it’s important to note these are case-sensitive:
- -X is the request method. It may be optional, but by stating it here we know which method is being used.
- -H refers to the header. You can send multiple headers.
- -d refers to the data
In the above command this is text. You also can refer to FileMaker local variables with @$data instead, so your cURL instead would read like this:
"-H "Content-Type: application/json" -d @$data"The body of the result shows a successful login with a token included in the result. This is the token used in subsequent commands. Keep in mind that tokens generally expire after a certain time. For the Admin API, this session limit is 15 minutes.
When using this token, it is set in the header, prefaced by the word “Bearer.” It looks something like what is shown in Figure 3:
We can test this in FileMaker as well. Attached is a simple file where you can enter your server name, Admin Console username and password, and log into the Server using the Admin API. If your connection is successful you’ll see a JSON result with your token.
Download the Admin API Test
Other Actions in the Admin API
Many of the other commands part of the collection of Admin API calls mirror what you would see in the Admin Console or the Command Line Interface, especially the latter. You can list databases and schedules, disconnect clients, close and open databases, and so on.
In FileMaker Server 17, a small number of actions is no longer available in the Admin Console, but requires either the command line or the Admin API. One of these is the setting to allow or disallow databases to be hosted without a password. See Figure 4.
This command requires a PATCH method, as shown in the documentation. In the header, you need the token and the content-type. The body will have the command “requireSecureDB” with the value either set to true or false in JSON.
https://{{host}}/fmi/admin/api/v1/server/config/security
{
"requireSecureDB": false
}Summing Up FileMaker 17’s Admin API
These are only a few of the examples of calls available through the Admin API. Previously, server admins relied on the Admin Console and Command Line Interface to manage server settings. This new tool may not necessarily replace either of these tools. However, the Admin API adds a new toolset for server admins to manage their server installations.
The Admin API opens up new possibilities to manage FileMaker Server settings. We now have a set of tools that take advantage of modern integration tools. What we build with these tools is up to us, and the possibilities are as open as the technology.
Update: FMS ACE
On June 5 Soliant announced an open source project that uses JavaScript and the Admin API to extend the Admin Console. This app shows how to view and manage backups in a web browser. Check it out.
Moving Forward in FileMaker 17
If you have any questions about how to use the Admin API or any other new features included in FileMaker 17, please contact our team. We’re happy to help your team determine the best way to leverage them within your FileMaker solution.
