Random thoughts, musings, and tech stuff

04 Aug 2013, 18:17

Share

Getting started with the Mirror API using node.js

I recently accepted an invite to purchase an Explorer Edition of Google Glass. Well, actually, the company I work for accepted (man, I love working for TiKL, Inc.), and I’ve been the one working on everything Glass at our office. (In case you’re wondering, a write-up on my thoughts about Glass so far is in the works.) So far, my efforts have been focused on building apks to run on Glass, which is incredibly easy if you’re and Android hacker like myself. What isn’t so easy for someone mainly focused on Android is trying to figure out the Mirror API.

The Glass team has put out a number of quick-start demos for working with the Mirror API, with a focus on getting over the OAuth2 hump. They demonstrate this in a number of languages, but they haven’t put out anything for node.js, which is what I use whenever I need a quick demo server for something. What Google has provided, is a github library that provides some simple mechanisms to interact with all of their services. It’s pretty awesome, and it allows you to pretty easily inspect the JSON data that is returned as the client object, and look at what’s available.

I figured out how to do the Mirror stuff by looking at the Google+ example in the googleapis github, implementing that first, so that I could get the authentication working. Then, making a couple of educated guesses about what I might need to change to get the Mirror API endpoints, along with looking at the Mirror documentation for Java and Python. Once I had G+ authentication up, moving it over to getting authenticated with the Mirror API was really easy, and getting valid requests written was not a big leap from there.

I still do not have much done, my main goal was to simply get node.js talking to Glass, which I did. Speaking of, here’s the github repo for my demo. Again, all this does right now is allows a user to authenticate, pushes the message ‘hello world’ to Glass, and requests the user’s timeline for the registered app.

Instructions

Follow the instructions in the Mirror API documentation for registering a new app. It’s basically the same flow for starting any new project using a Google API. Just follow the instructions, it’s easy. Once you’ve registered, pull down my repository and run npm install. This will install the googleapis npm package, as well as express.js if you need it.

Next, copy sample_config.json to config.json, and replace the values with those from the Google Developer’s console.

Run node app.js. Finally, visit the app in your browser, and authenticate with Google. You should get a push to your Glass with the text ‘Hello world’.

Digging in a bit

Now that you’ve seen this working, let’s look at some code. This is simply chunks from the app.js file, so if you want to just look at the whole thing at once, here it is.

First up, we’ve got some things to require, the googleapis, and the related oauth stuff.

We should look at the routes involved here first, before we look at anything specific to the API. Without the routes, you don’t really know what’s being called, and where the most important parameters come from, so here are the routes:

As you can see, there are only two routes, the root, and the oauth2 callback routes. We start by looking to see if we already have a token, if they don’t, we send them to Google to go request one. Otherwise, we use the token we have. If they didn’t have a token, they’ll return to us on the route oauth2callback (unless you change that route on your config), and we take the code provided in the request data to parse out their token.

**WARNING**: this is not intended for a multi-user case, just for you! Don't use this unmodified!

We’ll provide a couple of generic callbacks, for simplicity. Whenever you’re unsure of what to do next, or aren’t sure if something’s working, dump whatever data that you’ve got.

Alright, first thing’s first, we need to get ourselves a token. This method gets called when the user returns from giving us permission to connect to their account, and will use the provided oauth2Client to pull the token out of the code that is returned to us. We then store that token in the oauth2Client.

Once we have a token, we can do stuff with it. First thing to do is request a client that can make requests on the Mirror API, and in the callback, we can use the returned client to make those requests.

The following are two simple requests that you can make once you’re authenticated and get your client object:

I probably don’t really need to explain what’s going on there, it’s incredibly simple. But, in case you like reading things, the first one inserts the text ‘hello world’ into your timeline on Glass. If you’re using this with the account that you’ve attached Glass to, then that text will show up in your eyeball. It’s neat. The second request simply shows the timeline items that your app has generated.

Notes

Currently, this is incredibly simple, and as such is completely lacking in style, structure, and functionality. This is intended to demonstrate just two things, first how to authenticate with Google for the Mirror API with OAuth2, using node.js. Second, it begins to show how you can use node.js to make requests with the Mirror API. Think of it as the quick-start for node.js.