FileMaker 17 introduced a trial version of the Admin API. Now we have the production version of this RESTful API which will work with both FileMaker Cloud for AWS 1.18 and FileMaker Server 18. This represents yet another evolutionary step towards exposing more of the features of FileMaker Server for third-party integrations and convenient tools.
I have written such a tool in FileMaker Pro, which allows you to manage a FileMaker 18 Server. This Admin API tool is freely available here.
I approached this project as a way to not only learn how to work with the FileMaker Admin API but also work with REST APIs in general. To that end, I have purposely kept this file very lightweight and as straightforward as possible. My goal is to demonstrate how to work with this particular API instead of making a fully fleshed out user interface for general users. While fully functional, I’d like to make it easier for FileMaker developers to work with REST APIs in general.
This version of the Admin API does make several improvements. Some are not always well understood, but I believe some of that stems from the fact that this was written to adhere more closely to how REST APIs work, and not meant for general consumption of most FileMaker developers. In other words, the documentation may make more sense to a web developer used to working with APIs. Hopefully, the tool referenced above can help bridge the gap in understanding for the uninitiated.
Starting first with Authentication, the concept works a little differently in Oauth2 applications. There is a distinction between “authentication” and “authorization,” as these are two different but similar things. Authentication defines using credentials to authenticate against some identity provider. Authorization defines having the authority to perform certain tasks.
Authorization follows authentication. Once the login credentials are authenticated successfully, you receive an “authorization token” or “access token” that you then use to do whatever else you need to do. Your authorization token is like a key you use to unlock all the doors that work with that key, without having to authenticate at every door.
Using authorization tokens is a more secure and compliant way of working with REST services. It affords multiple levels of compliance with several different existing standards, such as Oauth2, an open standard for authorization.
As with many RESTful APIs, getting past the authentication and authorization is sometimes the most challenging part. Once you are past that, you can get to the business of working with the API.
HTTP Verbs and JSON
Other concepts that are important to understand when working with REST APIs such as the Admin API are the different HTTP verbs and working with JSON payloads. HTTP most commonly uses a couple of different verbs – also known as methods – to transfer data. At the core, these are GET and POST, but they also expand to include PUT, PATCH and DELETE which are really sent as POST transactions but with the method specified differently. These different verbs correspond to CRUD operations: Create, Read, Update and Delete.
The Admin API uses GET, POST, PATCH and DELETE to perform various operations. These are highlighted with buttons in my Admin API tool colored to match how they appear in the documentation and make it more obvious which one is being used for a given operation.
In any RESTful operation with the Admin API, you will get a response back in the form of JSON. In some operations where you also send data to the Admin API, that data will be sent as a JSON payload. You should already be familiar with JSON since the introduction of JSON functions in FileMaker 16. These native functions make it easy to construct and consume JSON while working with the Admin API. For more information about working with JSON, see the blog posts about creating JSON and parsing JSON by Anders Monsen.
All interaction takes place by using the cURL options available in FileMaker Pro, via the “Insert from URL” script step. My Admin API tool provides a “debug” popover to display the results of the last operation performed, including the JSON data and the HTTP response received from the server.
Divergent Feature Sets
FileMaker Server provides several administration tools. Those include the web-based Admin Console and the CLI (Command Line Interface), which is accessible from the server machine. Add that to the Admin API, and you have three possible options for managing FileMaker Server. However, each option has a slightly different set of features. Of the three, the Admin API has the least available in terms of what you are able to do, at least in the current version.
There are things you can do in the Admin Console that you cannot do with either the CLI or Admin API. Similarly, there are some things you can do with the CLI, such as disabling the default backup schedule or generating a CSR, that you cannot do with the Admin Console or Admin API.
In the current iteration, there is nothing you can only do with the Admin API that cannot be accomplished with either the Admin Console or the CLI. I expect that to change in future versions, as additional functionality can be added to the Admin API. Add to that the fact that FileMaker has a robust and involved community, which allows third parties to come up with innovative and interesting solutions that use the Admin API.
One last thing to note is that the Admin API now requires all communication to go over port 16000, which is also the default required port for using the FileMaker Admin Console. This allows you to control access to that port and still allow generally used ports for web publishing and WebDirect, 80 and 443.
To find further documentation that gets installed with FileMaker Server, just go to your server’s URL in a web browser, with “:16000/fmi/admin/apidoc/” appended.