I’m shamelessly excited about the upcoming olympic games. I’m a sucker for both the competition and the cheesy human-interest stories…. I thought the games would make a good excuse to show how a simple API can be built and launched from scratch with modern tools.

Put on your propeller beanie and let’s take a gentle geeky look at how I built it.

Olympics Medals API

The project was to launch an web-based API that returns JSON data on the current medal count for the Sochi 2014 games. In plain english, that means a URL:

• http://olympics.clearlytech.com/api/v1/medals

which returns raw data that can easily be consumed by another computer program.

Why would we want this? This is very similar to almost every API that powers mobile apps today. Most iPhone and Android applications are constantly visiting URLs like this to get the data they need to update views in response to user input, loading a new screen, etc. These things power nearly every interaction you do on mobile, and a good chunk of the web too.

In our specific case, we return JSON text as seen below, with the latest medals counts for all the olympic countries. You’ll get the full data if you click the link above.¹

[
    {
      "country_id": "united-states",
      "country_name": "United States",
      "rank": 1,
      "gold_count": 12,
      "silver_count": 14,
      "bronze_count": 6,
      "medal_count": 32
    },
    {
      "country_id": "germany",
      "country_name": "Germany",
      "rank": 2,
      "gold_count": 8,
      "silver_count": 16,
      "bronze_count": 1,
      "medal_count": 25
    },
    and so on, for all 94 countries represented.
]  

There’s also another URL for retrieving the medal counts for a particular country:

• http://olympics.clearlytech.com/api/v1/medals/united-states

That one returns a very little bit of text:

{
    "country_name": "United States",
    "rank": 1,
    "gold_count": 12,
    "silver_count": 14,
    "bronze_count": 6,
    "medal_count": 32
}  

Getting the Data

This app was a fun reason to try out a newly launched tool called Kimono. They offer a service which scrapes structured data off web pages for you. I created a Kimono scraper in only a few clicks which retrieves the raw data directly from Sochi2014.com. Wouldn’t have been hard to do myself, but developers love shortcuts wherever we can find them.

It’s worth noting here that my API is a wrapper for a Kimono API, which is scraping the official Sochi website, which is displaying raw data from the International Olympic Committee medal standings API. These kinds of services-built-on-services are what makes the modern web so exciting and powerful, while simultaneously confusing and often fragile. If I were building a real production-quality API for olympic medal standings, I’d almost certainly try to license the raw data source to make my app faster and more reliable. But this approach will work for our purposes, and allowed me to get the whole API built and deployed in only a couple hours.

Building the App

I chose the lightweight Ruby Padrino framework for this app. It doesn’t have as many advanced features and support as something like Ruby on Rails, but it’s fast and easy to work with for a tight small project that doesn’t need a fancy front-end or even a database (though you can do all that with Padrino too).

You can find all the source code for this application open-sourced on GitHub. If you haven’t poked around at an app like this before, indulge yourself, and go take a look at just three files:

1. The main application file shows three simple URLs. Our two API endpoints, and the root, which redirects to our documentation.
2. The MedalData class which does the work of grabbing the raw data and arranging it to match what we return via JSON.
3. A simple automated test for MedalData that makes sure future changes to my code or the Kimono scraper don’t break the behavior I’m expecting. This is a great example of how simple an automated test can be.

All the rest of the files in the project are just decoration, configuration, documentation, the boilerplate plumbing that Ruby and Padrino require to do the work. Not that hard, right?

Documenting the API

Developer tool Apiary maintains an open standard for documenting APIs like this one, called the API Blueprint.

I wrote up a similar description as above, but in their specified format, which is shown when a user visits http://olympics.clearlytech.com/.

Simple documentation like this goes a really long way towards convincing others to consume your API. Developers love this stuff.

Deploying It To The World

I decided to launch it on the mind-bogglingly easy Heroku platform. I created a new app, ran some git commands (Heroku manages your code by using the git source control tool that your developers are probably using anyway), and voilà! Instant public application.

Technically, the Heroku app runs at http://olympics-api.herokuapp.com/, but I told it to answer to http://olympics.clearlytech.com/ as well, by putting an entry in my DNS zone, managed by Amazon Route53. This may seem like a lot of moving parts, but wiring this kind of thing up is second-nature stuff to any full-stack developer worth her salt.

The whole process of setting this up on Heroku (including signing up for the service, setting up the app, deploying it, and changing my DNS) took about 10 minutes. There isn’t a faster way right now to deploy a low-volume application for public consumption.