kdykes edited this page Dec 21, 2012 · 30 revisions

A Saner (and Geekier!) Approach to Working with APIs

Update -- see also the blog post The last gem you'll ever need? which provides more background on this project.

Update -- please join us in the Geekier Google group where there is ongoing discussion on this project

What is this?

While building rules.io we found ourselves connecting to lots of APIs. We also found ourselves building user interfaces that we knew would eventually connect to an API of our users' choosing -- but we wouldn't know which API until runtime. Working with APIs in this very dynamic way led us to build some interesting technology, and gave us some fresh perspectives on how best to use API-based services from web and mobile applications.

With Geekier we are extracting part of what we've built for rules.io as an open source framework.

What "fresh perspectives"?

Working with APIs can be a nuisance, because you have to

  • study the API documentation (often complex, or poorly written)
  • find and evaluate available libraries for using the API
  • write code that couples your application with the API -- or define an abstraction layer
  • worry about the performance impact of making synchronous API calls -- or put in place a framework for background jobs
  • decide how to handle errors
  • make updates when the API changes

We make all of this easier. Geekier includes

  • machine-readable API descriptions, created by experts and organized around how to use these APIs to get things done
  • a simple abstraction layer to use in your code, avoiding vendor lock-in and providing lots of flexibility
  • a service framework that actually makes API calls
  • ready-made, easily customized solutions for logging, retry policies, error reporting, and analytics


How does this work?

API descriptions

Geekier depends on having machine-readable API descriptions. These descriptions are based on Swagger, and include information about

  • HTTP connection info (e.g., path, method)
  • responses and errors the API can return
  • parameters (optional vs required, their types, and possible values)

Having all this info in machine-readable form makes it possible to build user-friendly interfaces that rely on 3rd party services, without knowing in advance exactly which APIs will be involved. For example, a monitoring application might want to include a form for setting up alerts. Rather than offering a limited choice of email or SMS (for example), an application that uses Geekier can instead allow the alert to be sent via any of the connected Geekier APIs.

API connection factory

At the heart of the Geekier implementation is a factory that builds API connection objects for talking to any of the described APIs. One way to use Geekier is to use this factory directly in your code.

Geekier as a service

In most cases, a better way to use Geekier is to use our simple event-based abstraction layer in your application. The Geekier Service will consume this event stream and make API calls for you in the background. For example, you might send an event every time a new user creates an account in your software. Then if you want to send each new user a welcome email, you can create a mapping in Geekier that uses Sendgrid (for example) to send that message. (The mapping would describe how to transform the data from the account creation event into the parameters needed for sending an email via Sendgrid.) Later, if you also want to see graphs plotting account creations, you might create another Geekier mapping that sends data points to Librato, and so on.

Getting all of the API-specific code out of your applications will make your applications simpler, easier to test, and much more flexible.

Event Maker

Geekier can also be used to connect together existing web services, even if they weren't designed with Geekier in mind. The Geekier Event Maker will create an event stream from any web service (with a relatively sane REST API), and these events can be mapped and acted on just like the events from any other application.

How can I help?

If you believe that an interoperable web needs an open framework for connecting applications and services based on self-describing APIs, join us!

Extending the reach of Geekier benefits the entire community. You can do this by contributing new API descriptions, or libraries making Geekier accessible from other programming languages (so far we've got Ruby covered). Email us at team@rules.io if you'd like to get involved.