Last Sunday, Terrible Labs hosted an APIs and IPAs event to encourage development on RunKeeper’s Health Graph API. I attended this hackfest and had a blast. It is worth reading the recap on the RunKeeper Blog and watching the video.
While some good progress was made in understanding the API and creating some apps, we realized we needed more time to take things further. Luckily there’s been a commitment to have several follow-up hack sessions so that veterans can continue their efforts and newbies can learn and bring some fresh ideas. You should come to the event this Wednesday. Sign up and then continue reading for some info that should help bring you up to speed and let you hit the ground running.
Note that while most of the advice in this post is targeted towards back-end developers, we certainly could use the touch of front-end developers as well.
What You Need to Know About the Health Graph API
Firstly, you should take some time to read the documentation. When talking through app design, we lost a lot of time to not really understanding the API. Here are some important points:
- You need to register an application to get the API keys you need to get started. By default, your app is restricted to write-only permissions (with a few small exceptions). You probably will want to request permissions to “Read Health Information” as part of app registration. The policy seems to be to hand these out freely as long as you aren’t planning to do anything sketchy and you agree to their terms.
- The API is oriented around the data of single users. After a user completes OAuth through your app, you make your API requests by passing in that user’s OAuth token. This means that while your app has control over reading (with permission) and writing data for current users, you can’t do things like look up activities for users who haven’t used your app. If you want to have real data to play with, the easiest way is to generate your own by recording a few activities via the RunKeeper app.
- The Health Graph API is pretty new (~ 3 months old). RunKeeper is still actively making improvements to it to make things easier for developers using it. There is an active google group where you can post questions or suggestions – and they reply quickly.
- Because the API is still young, there isn’t an ecosystem of libraries to use. Joe Lind, Will Mernagh, and I worked on a ruby library BabyTooth to make consuming the API less painful (it handles OAuth and provides an OO interface to the data). It is important to note that BabyTooth doesn’t support writing data… yet. During the original event I briefly prototyped what a read/write library might look like as part of my example sleep tracking app (code | demo). Looking at github also turns up node-runkeeper, a Node.js client (also in its infancy). If you want to hack on a library in your preferred language or improve one of these, you’ll have some people around to give you pointers.
Sign Up and Show Up
By familiarizing yourself with the API and the work that’s been done so far, you should be ready to help create something awesome. Whether you’re interested in helping to make one of the existing libraries or apps more robust or you want to work on a completely new idea, sign up and show up on Wednesday.
Resources
Documentation and Background
Code
- BabyTooth – a Ruby gem for consuming the Health Graph API. No write support yet, but it will handle the OAuth and read requests.
- node-runkeeper – a Node.js library that handles OAuth and consuming some resources.
- sleeptracker – my rudimentary Sinatra app for self-reported sleep tracking.