Writing a Personal Automation API: Part 1 - Getting Started

In my previous post, I outlined how every dev should write a personal automation API. I specifically mentioned that the easiest/cheapest way to do this is probably to write your API in Google Apps Script. Here I’m going to walk through how to start building the API framework in Google Apps Script.

A quick intro to Google Apps Script

I find it kind of hard to describe Google Apps Script, so I’m just going to let Wikipedia do it:

Google Apps Script is a scripting language for light-weight application development in the Google Apps platform. It is based on JavaScript…, however instead of running on the client, it gets executed in the Google Cloud… Google Apps Script “provides easy ways to automate tasks across Google products and third party services.”

Google Apps Script provides you an IDE to edit your Google Apps Script project (a collection of JS-based .gs files) that are hosted on your Google Drive and execute on Google’s servers. The big benefits/features of Google Apps Script are:

  • You don’t have to host anything or add support for HTTPS
  • Lot of libraries available
  • Easy cron job creation (called “triggers”)
  • Functions to issue and handle web requests

Over the next few posts, we’re especially going to use the last two to turn our script into a little API.

Writing your first API in 90 seconds

Starting your script

In your main file (Code.gs by default), delete the default myFunction() and create a new function called doPost() to handle HTTP POST requests. Naming this function doPost() is all that is necessary to tell Google Apps Script that this function will be the highest-level handler for all incoming HTTP POST requests to the script’s endpoint. For now, just return the text “Hello world!”

function doPost(e) {
  return ContentService.createTextOutput('Hello world!');

Now, deploy the script out to the wild web using the cloud icon in the toolbar. In order to have it easily accessible to IFTTT, other APIs, and any other clients you want to use, we’ll to make it publicly available. Set the “Execute the app as” dropdown to “me (your email)” and the “Who has access to the app” dropdown to “Anyone, even anonymous.” Google Apps Script will inform us that the app is successfully deployed to https://script.google.com/macros/s/some-big-long-identifier. Save that URL– it’s what all your processes will use to integrate with your API.

Testing your API

You can test your API using any HTTP request tool / response inspector. Fiddler comes to mind, but my personal favorite is Postman. It’s a lot simpler, and as a Chrome app, it’s inherently cross-platform and requires no program installation. Paste the URL for your Google Script and submit a POST request to that endpoint. You should see your Hello world looking back at you.

In my next post, I’ll go over how to start actually doing something with the API we’ve built.

--- ---