Monday, April 27, 2015

Connecting to the Jawbone UP API with Node.js

As a developer, I cannot help but want to access the huge amount of step count and sleeping habit data my Jawbone UP has on me. There is so much data! So I began looking into how to pull in this data using the Jawbone UP API and Node.

I found examples of how to work with the Jawbone UP API and Node across the web but they were all quite involved and had a lot of moving parts, along with some outdated modules (like older versions of Express). In this article I want to focus on the absolute basics—no worrying about saving user data into a database, creating accounts or connecting up social logins. We’ll focus on the core things you need to know to get a Node server to authenticate with the Jawbone API and return user data.

All of the code for this demo is available on our GitHub repo.

Setting up a Jawbone App

The first thing we’ll need is a new Jawbone app set up under our Jawbone account. This is the app which users will be authorising to access their data.

Start by logging into the developer section of the Jawbone site by going to http://ift.tt/1aWcAZn and clicking the “Sign In” link on the bottom left. You won’t need a specific Jawbone developer account as they will allow you to log in using an existing Jawbone account.

The Jawbone Developer Sign In

Once logged in, head to http://ift.tt/1Jvx0s5, or click the “Manage Account” link in the left hand menu under “Account”.

Manage Account

On this page, you’ll reach your developer account page. From here, click “Create App”.

The Developer Account Page

On the page that loads you will be prompted to enter the details of your app:

  • Name - The name of your application, I entered “Jawbone UP Node Demo”.
  • Description - This is a short description that will come up on the user’s UP App Gallery.
  • Long Description - This comes up on the detail page of the app in the app gallery.
  • Logo - Upload a logo for your application. If you receive an error about “Select” (strange I know, but it’ll make sense to the few people who follow along and get that message), chances are your logo image is too big.
  • URL - Your app’s homepage
  • Authorization URL - The URL that your login page will be found at. For our test purposes, enter in https://localhost:5000/login/jawbone.
  • OAuth Redirect URIs - URLs that your application is allowed to redirect to once the user has been authenticated. In our demo, we’ll enter in https://localhost:5000.

Once you click to create the application, you’ll be directed to the page with a list of your apps. Your newly created app should look similar to mine:

The newly created app

Take note of the “Client Id” and “App Secret” - these are what you’ll need to connect up to the Jawbone API.

Starting our Node App

I’ll be including all our Node server code in one file called server.js. We start by requiring the necessary npm modules for our server.

First, we set up a basic Express app.

[code language="js"] var express = require(‘express’), app = express(), [/code]

We then require ejs (Embedded JavaScript), which allows us to insert JavaScript into our HTML templates. We’ll use this to display JavaScript variables within our returned HTML.

[code language="js"] ejs = require('ejs'), [/code]

In order to be able to authenticate with the Jawbone API and redirect back to our application, Jawbone requires that we redirect to a page over https. To do this, we’ve got to include https.

[code language="js"] https = require('https'), [/code]

Next, we include fs, which allows us to read the file system. We’ll need this to read in server certificate files to enable https.

[code language="js"] fs = require('fs'), [/code]

We’ll also need body-parser to enable us to handle JSON requests:

[code language="js"] bodyParser = require('body-parser'), [/code]

The Jawbone UP API uses the OAuth 2.0 protocol for authentication. Basically, this means in order to have a user sign in with their Jawbone account and give us permission to access their data, we need to go through this protocol. Luckily, npm’s passport module contains a module called passport-oauth which supports this. We set up passport in our app along with OAuth 2.0 like so:

[code language="js"] passport = require('passport'), JawboneStrategy = require('passport-oauth').OAuth2Strategy, [/code]

We’ve then got a self explanatory variable that stores the port we’ll be running on.

[code language="js"] port = 5000, [/code]

Next up, we will be storing all the values needed for authentication in Passport and OAuth 2.0 inside jawboneAuth. This is the moment you’ll be using the “Client Id” and “App Secret” values we took note of earlier when we registered our app.

[code language="js"] jawboneAuth = { clientID: 'jUvu1_4u_mA', clientSecret: '8961265d16ac678948006c2944ed85dbeeaab547', authorizationURL: 'http://ift.tt/1oX9QCI', tokenURL: 'http://ift.tt/1F4mvI4', callbackURL: 'https://localhost:5000/sleepdata' }, [/code]

Here is an overview of what these values mean and/or where they’ve come from:

  • clientID - this is the “Client Id” listed for your Jawbone app.
  • clientSecret - this is the “App Secret” value below it.
  • authorizationURL - this is the location of the UP OAuth 2.0 authentication page that the user will be redirected to.
  • tokenURL - this is the URL in the Jawbone UP API that we must make a HTTPS call to, in order to request an access token. This token is what we need to include in our calls to the Jawbone UP API to prove we are authorized to make those requests for data. In the Jawbone UP API, this token lasts for a year, so you can store it in a database and have a user connected to their Jawbone account for a year before needing to reauthenticate them. We won’t be looking at storing users and such in this tutorial, but it is good to keep in mind if you’re looking to push this further.
  • callbackURL - the URL on our site which Jawbone will direct the user back to once they’ve successfully given us access to their data. For us it is a page to display the sleep data.

The last variable we’ve got to define is our sslOptions which contains all the details we need to provide to our server to allow us to run this server using HTTPS. I’ll go over each of these in detail later in this article when explaining how we set up HTTPS.

We then include a few lines defining some basic Node app functionality which will be familiar to Node developers out there:

[code language="js"] app.use(bodyParser.json()); app.use(express.static(__dirname + '/public')); app.set('view engine', 'ejs'); app.set('views', __dirname + '/views'); [/code]
  • bodyParser - allows us to parse JSON objects.
  • Static folder - defines where our static files like images will be on the server (in our case, /public folder).
  • EJS - assigns the ejs module as our template engine.
  • Views folder - defines where our ejs view files will be on the server (in our case, the /views folder).

In order to initialize Passport within Express, we run the following line:

[code language="js"] app.use(passport.initialize()); [/code]

As a note, there is more to set up in Passport if we wanted to have persistent login sessions. In this case, we would need to set up sessions. However, for this tutorial, we’ll just focus on the initial stage of getting the data down from the Jawbone UP API and won’t worry about login sessions.

Continue reading %Connecting to the Jawbone UP API with Node.js%


by Patrick Catanzariti via SitePoint

No comments:

Post a Comment