We recently released our gManipulator plug-in, which connects your FileMaker solution with Google and allows users to exchange data between FileMaker and Gmail, Google Contacts, Google Calendar, and Google Tasks using a personal, free account or a G Suite account.
Interested in learning more? Read on for our developer’s story on making it.
The Google Suite of integration APIs are much like all other APIs: they are designed to allow developers to connect their “third-party” application to a given service.
Much to the joy of any developer with even a small amount of practical experience, the Google APIs contain detailed documentation about their endpoints, how the data should look going up and coming back down, examples and sample code provided in numerous different programming languages, caveats and concerns for many different scenarios… The list goes on.
There is one noticeable difference between the Google Suite of APIs and the APIs of some other well-known services, such as Exchange Web Services or Intuit’s QuickBooks Online service: there are over one hundred APIs to choose from.
(Just a snippet from the products listing at https://developers.google.com/products/)
There is an API for Google Calendar, an API for Google Analytics, an API for Google Maps, at least two different APIs for Google Contacts (legacy “Data” and modern “People”)… It’s stormy seas ahead for any developer looking to create a one-stop shop for even a handful of these services.
A developer needs to know several things before tackling such a trove of options:
- Which services do I need to provide to my users?
- Are there multiple services that provide the same benefit? If so, which one would fit my situation better?
- What language should I use to connect to these endpoints?
- How many of my chosen service APIs depend on other service APIs?
- How can I tie all of these APIs together?
The Lowest Common Denominator
In crafting the gManipulator plug-in, I myself had to tackle these particular questions and navigate the swells and waves that the Google Developers portal represented.
With a desire for familiarity, I focused on the four primary Google API offerings of Google Mail (or “Gmail”), Google Calendar, Google Contacts, and Google Tasks (which is conveniently meshed into the actual interfaces for Gmail and Contacts). So I picked out my APIs and brought them together: the Gmail API for handling mail messages and user labels; the People API, since it was the most modern way to talk to Contacts; Calendar API, for working with calendar events, reminders, and calendar folders; and Tasks API, because everyone needs to stay on task.
Evaluating each of these APIs, or as I like to call them “modules”, a recurring pattern bubbled to the surface that I instantly jumped upon.
As if ordained by the Great Spirits of Programmers Past, they all had the same handles for authentication, namely Google’s OAuth 2 Authentication API. That made my job so much easier, especially when I discovered that one of my favorite programming languages, the .NET-loving behemoth C#, was fully represented in stub code and example snippets sprinkled throughout the different module documentation like spices for the perfect soup. This would be a cinch, I told myself.
Navigating a Minefield
As with any major project, there is no “perfect” development outcome. It was easy enough to push through the authentication process, as the sample code and handy SDK files (software developer’s kit; I seriously highly recommended you keep an eye out for these gems), made putting together a solid workflow for users to sign in and authorize the plug-in quite easy.
Working on the other individual modules, however, was like navigating a minefield: every step came with a risk of finding some explosive detail that prevents you from making your workflow go just the way you want it.
For an example, let’s consider a FileMaker client plug-in and converting it to run for FileMaker Server. For those not in the know, FileMaker has a simple but efficient document for tips and tricks when converting a client-side plug-in to run on the server.
Some important considerations to make when doing this, however, include how portable the software is that the plug-in is using; for instance, code that requires a UI (user interface) is not fit for running server-side, as any UI prompt waiting for a response will ultimately time out the server, and no one wants to watch a program crash and burn.
(Simple example of using compiler tricks to make sure the code will work as well on a server as it does on a client machine)
When carrying over the plug-in, every bit of code had to be scrubbed for UI; no new authentication (as like one that would pop up a browser window and demand user interaction), anything done asynchronously would need to be done synchronously, and even the supporting code itself needed updating to protect it from displaying error dialog messages. It took numerous iterations (and gave me at least ten new gray hairs) before both flavors of server would accept the plug-ins and perform without any runtime problems.
Shining like a Beacon
Let’s talk for a moment about sample applications.
APIs are fantastic, providing all the knowledge a developer can stomach about one or more services. SDKs are even better, giving developers a direct way to interact with said services in the way the service designer intended. But the true hero of the day is the lowly sample application.
Sample applications are ideal for reviewing the source code provided by the API and SDK developers themselves, and act as a great testbed for implementing your own spins on the code. The screenshot above is a simple example of a sample application, based on snippets of .NET code examples from the Google API and sample apps from other programming languages that can be found on the API reference pages.
With a sample application, you not only get to see the SDK in action, but you can find new and unique ways the SDK is implemented that may not have even been mentioned in the API’s documentation. I can’t tell you how many times I’ve come across a sample application that made me lean back and say, “Okay, I didn’t think about running it that way, that’s pretty cool!” Plus, it’s always nice to see those examples so I can mold something similar with my own code and have a baseline to compare against when it comes time to throw caution into the wind and test it all.
The Road Less Traveled
When it all comes down to it, implementation of a RESTful API, such as Google, varies greatly by developer.
In my particular case, it made more sense to me to wrap the desired endpoints of Google’s many services into a single compiled FileMaker plug-in, mostly due to my familiarity in the programming language required, the experience I have in plug-in development, and how my mind works out organizing the different features and properties of data. This isn’t the only way such an API can be used for a FileMaker solution, of course.
It is entirely possible, for instance, to use a custom FileMaker database to perform everything that would be required to push emails, modify contact information, manage calendar events, and more. This would require a full understanding of the OAuth 2.0 workflow and how to properly submit and retrieve authentication information, as well as signing requests; using FileMaker’s scripting and calculation engines to properly parse the different forms of data based on the modules; even use custom hooks with external PHP pages to help offload some of the work to a web server. It really depends on the developer’s own programming strengths and the amount of blood, sweat, and tears they wish to put into the project.
Hopefully this little insight into one developer’s growing pains of working with the Google Suite of APIs helps to shed some light on what working with a third-party API can be like. It can be tough, it can be grueling, it can be unforgiving (I’m looking at you, Syntax Errors), but in the end, you get a product that feels like “your baby”. And, really, that’s all a developer really needs when they create. That, and maybe a magic wand to make code compile without problems. That would be nice, too.
If, after reading this, you want to learn more:
- Make sure you check out the integration training course that we’ll be releasing in July at Productive Computing University.
- Download the gManipulator plug-in demo file to connect your FileMaker solution with Google and exchange data between FileMaker and Google Mail, Google Contacts, Google Calendar, and Google Tasks. With the plug-in you can create a cross-platform and client or server-side integration with Google Services.