Home

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. We use Facebook’s faster read-only servers whenever possible, and support a variety of HTTP libraries so you can make snappy requests however you like. That, of course, that brings us to our next topic:
• Flexible: Koala should be useful to everyone, regardless of their configuration. We support Ruby 1.8.7, 1.9.2 and 1.9.3, as well as JRuby, Rubinius, and REE, and use the Faraday library to provide complete flexibility over how HTTP requests are made.
• 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.2 beta, coming 8/17
[sudo|rvm] gem install koala # 1.1

Or with Bundler:

gem "koala", "~> 1.2.0beta" # 1.2 beta, coming 8/17
gem "koala" # 1.1

Once that’s done, using Koala is simple:

require 'koala'
 
# initialize a API connection, for instance
# pre 1.2beta:
@graph = Koala::Facebook::GraphAPI.new
# with 1.2beta:
@graph = Koala::Facebook::API.new 

Learning about Koala

Check out our different wiki pages for more information:

• Graph API: accessing Facebook through the Graph API
• Rest API: using the legacy REST API
• OAuth: all things authentication
• Realtime Updates: subscribing to users’ changing info
• Batch Requests: upload photos via the Graph API
• Uploading Photos and Videos: upload photos via the Graph API
• Test Users: creating and managing test users
• Koala on Rails: a few tips and tricks for using Koala in the Rails environment
• Extensions: how you can extend Koala to meet your own needs
• HTTP Services: how to configure how Koala makes HTTP requests
• Testing: how to test Koala
• Rails 3 Facebok Example Using Koala: Rails 3.0.7 example for using Koala

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.