-
Notifications
You must be signed in to change notification settings - Fork 0
Home
We’re excited to announce the release of Koala, a lightweight and flexible Facebook library for Ruby.
Using Koala, you have complete access to all of Facebook’s APIs — the new Graph API, 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.
- 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.
Start by installing the gem:
gem install koala # sudo if needed
Once that’s done, using Koala is simple:
require 'rubygems' require 'koala'
# initialize a Graph API connection, for instance @graph = Koala::Facebook::GraphAPI.new
Check out our different wiki pages for more information:
- Graph API: the main API for accessing Facebook
- Rest API: another comprehensive Facebook API
- OAuth: all things authentication
- Realtime Updates: subscribing to users’ changing info
- Uploading Photos: 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 work with other HTTP libraries
- Testing: how to test Koala
- What's Next: what we’re working on now.
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.
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.