Skip to content

Home

Jump to bottom Edit New page
arsduo edited this page Jun 30, 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 Graph API (including batch requests and photo uploads), the Rest API, realtime updates, test users, 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 and returning simple JSON hashes.
  • 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. Of course, that brings us to our next topic:
  • Flexible: Koala should be useful to everyone, on any system.  (We’re working toward full compatibility with all versions of Ruby.  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:

[sudo|rvm] gem install koala --pre # 1.1 release candidate
[sudo|rvm] gem install koala # 1.0

Or with Bundler:

gem "koala", "~> 1.1.0rc" # 1.1 release candidate
gem "koala" # 1.0

Once that’s done, using Koala is simple:

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