Clone this wiki locally
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.
- 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
Or with Bundler:
Once that’s done, using Koala is simple:
require 'koala' # initialize a API connection, for instance # 1.2 and beyond: @graph = Koala::Facebook::API.new # pre 1.2: @graph = Koala::Facebook::GraphAPI.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: get multiple objects in one call
- Uploading Photos and Videos: upload photos via the Graph API
- Test Users: creating and managing test users
- Acting as a Page: how to interact with Facebook on behalf of your Page
- HTTP Services: how to configure or troubleshoot how Koala makes HTTP requests
- 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
- Testing: how to test 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.