« Beeminder home

Beeminder Blog

My endpoints, let me show you them

After adding Jawbone last month, I realized that we could be approaching an asymptote in Beeminder’s coverage for integrations. We’ve covered some of the most popular apps and devices, but their numbers are exploding, and there’s no way we could hope to keep up. Even by beeminding them — it doesn’t pass the want-can-will test. We still get a ton of requests for integrations though, for everything from Codecademy to Mint to Google Glass. And it seems like whenever we add an official integration, there are always a few people who wish it worked a little differently [1] — wanting to beemind their vocabulary count on Duolingo instead of their points, for example.

As it turns out [2], all the tools for building and modifying Beeminder integrations already exist! We’ve done a bad job advertising this fact, though, so here’s how you can 1) beemind anything under the sun, and 2) let other Beemindees do the same thing — because who doesn’t like to see the things they’ve built used by other humans?

We’ll start with an example. Astute readers will recognize URLminder from such blog posts as last month’s NaNoWriMo announcement. URLminder is a standalone app that takes a number of URLs, and, once per day, counts the number of words in those documents and reports the total to Beeminder. It’s deployed on Heroku and its source code is published on GitHub. [UPDATE: URLminder is now built in to Beeminder, not hosted as its own thing on Heroku anymore.]

So how does it work? Assuming you don’t want to just RTFC. The app itself is a very simple Rails app. There’s a model for a Goal, each instance of which corresponds to a Beeminder goal. A Goal has an array of public URLs that we want to count words for, and some methods to go out and count the words.

The interesting part is how it connects to Beeminder. URLminder takes advantage of the fact that Beeminder is an OAuth2 provider, thanks to the excellent provider gem from Songkick. So when someone signs up for URLminder, they’re directed to Beeminder where they see a screen asking them if they want to allow URLminder to access their Beeswax. If they do allow it, Beeminder gives URLminder an access token, and now URLminder can do things on that user’s behalf, like create a goal and update it when the word count changes.

Here’s the best part — you can do this yourself! Anyone can create a Beeminder app by going to beeminder.com/apps. You’ll also see apps that you’ve authorized here. You’ll get a client_id and a client_secret that you’ll use to allow people to authorize your app to access their Beeminder data. [3] Since these are sensitive, they’re not checked into version control in URLminder, but there is a sample config file you can crib from. I’m using (approximately) the approach outlined in a blog post by Tammer Saleh.

If you want to try this out, you could fork URLminder and have it go out and fetch, for example, your points total from Codecademy. The total is sitting there teed up in a nice little span with a class called “stat-count” — it’s just waiting for you to point Nokogiri at it! The only real modification would be to tweak the count_words method in the Goal model and plug in the client_id and client_secret values from the Beeminder app you create.

So get coding! We’ll put the integrations in a gallery of some kind once we figure out a process for vetting them.


Image credit: Hueniverse


[1] I have yet to hear from anyone who [thinks our mother is cheap](https://www.beeminder.com/contact ).

[2] Douglas Adams on “it turns out”:

Incidentally, am I alone in finding the expression ‘it turns out’ to be incredibly useful? It allows you to make swift, succinct, and authoritative connections between otherwise randomly unconnected statements without the trouble of explaining what your source or authority actually is. It’s great. It’s hugely better than its predecessors ‘I read somewhere that…’ or the craven ‘they say that…’ because it suggests not only that whatever flimsy bit of urban mythology you are passing on is actually based on brand new, ground breaking research, but that it’s research in which you yourself were intimately involved. But again, with no actual authority anywhere in sight.

[3] If you don’t want or need to use Rails for your app, and want to use some framework we probably haven’t heard of, you might find the Beeminder omniauth strategy useful.