Skip to content

Home

Jump to bottom Edit New page
arsduo edited this page Jan 26, 2011 · 47 revisions

We’re excited to announce the release of Koala, a lightweight and flexible Facebook library for Ruby.

Introductions all around

Using Koala, you have complete access to all of Facebook’s APIs — the new Graph API (including photo uploads), the old REST API, realtime updates, and OAuth validation. Before we delve into using Koala to read and write from the social graph, though, it’s worth a moment to go over our four goals for the library.

Koala’s goals

  • Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing support for the complete API (including the Graph API, Rest API, and OAuth authentication) and returning simple JSON.  (We clock in, with comments, just over 750 lines of code.)
  • Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. When possible, we also use Facebook’s api-read servers for faster responses (as of 1.0). Of course, that brings us to our next topic:
  • Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using other HTTP libraries if you prefer HTTParty or another library.)
  • Tested: Koala should have complete test coverage, so you can rely on it. (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)

Also, we want Koala to be great Ruby, and to be responsive to your needs and suggestions. Please, feel free to send us a Github message with any suggestions, feedback, or comments you have.

Getting the Code

Start by installing the gem:

# 1.0 beta!  check it out!
sudo gem install koala --pre
# or if you hate photo uploads and speed and want 0.10:
sudo gem install koala

Once that’s done, using Koala is simple:

require 'rubygems'
require 'koala'
# initialize a Graph API connection, for instance
@graph = Koala::Facebook::GraphAPI.new

Learning about Koala

Check out our different wiki pages for more information:

A note on namespaces

To avoid conflict with anyone else’s Facebook class or module, I’ve namespaced everything inside the Koala module. I highly recommend you add ‘include Koala’ (or even ‘include Koala::Facebook’) to skip all that wordiness if your environment doesn’t already have a Facebook class.

History, for the historically minded

How Koala came about: I was lucky to go to Facebook’s F8 conference a week and a half ago, and even luckier to have the chance to meet several Facebook Platform engineers (a big thank-you to Context Optional, my employer, for making both possible).  As you may know, Facebook released their new Graph API at F8 — a much, much, much simpler way of accessing Facebook data.  The Facebook engineers I met there were justifiably proud of the new interface and how its simplicity allowed them to write a complete Python library in just over 200 lines of code.

As we were talking, those engineers offhandedly suggested someone port their new library to Ruby — a challenge too good to refuse.  The public beta of their new Javascript SDK had already won me over to the simple API philosophy of a generic API accessor providing JSON output, and I jumped at the chance to bring that approach to Ruby.  By the end of the conference, I could fetch data, and by the end of the night, I had read/write access to the entire social graph.  I’ve spent the next week building out the library with Rafi Jacoby at Context Optional, and now the Koala gem is ready for use.

Add a custom footer
Add a custom sidebar
Clone this wiki locally