Home

Welcome to Koala, a lightweight and flexible Facebook library for Ruby. This wiki covers a number of use cases you might encounter working with the Facebook API;

As far as I know, all information in here is accurate as of February 28, 2017. If you find any errors or outdated information, please go ahead and edit the wiki or open up an issue. Facebook changes often and it’s a lot of work to keep up with it. Your help makes all the difference.

Introductions all around

Using Koala, you have complete access to all of Facebook’s APIs — the Graph API (including batch requests and photo uploads), 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

• Complete: Koala should make it easy for you to use any of Facebook’s APIs. Because those APIs can change and grow at any time, that means Koala should be…
• Lightweight: Koala should make as few assumptions about either Facebook APIs or how you use them as possible. Thanks to Facebook’s solid design, that’s relatively easy: you’ll mostly work with general methods applicable to any object or edge of the social graph and will get back standard Ruby hashes in response.
• Flexible: Koala should be useful to everyone, regardless of their configuration. We support all currently-supported versions of MRI, JRuby, and Rubinius, 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 open up a Github issue with any suggestions, feedback, or comments you have.

Getting the Code

Start by installing the gem:

[sudo|rvm] gem install koala

Or with Bundler:

gem 'koala'

Once that’s done, using Koala is simple:

require 'koala'

# initialize a API connection
graph = Koala::Facebook::API.new(access_token)

Learning about Koala

Check out our different wiki pages for more information:

• Graph API: accessing Facebook through the Graph API
• Debugging: running into problems? Here are a few hints.
• Realtime Updates: subscribing to users’ changing info
• Batch Requests: get multiple objects in one call
• OAuth: all things authentication
• 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
• Extensions: how you can extend Koala to meet your own needs
• Testing: how to test Koala

The complete list of wiki pages has additional examples, how-to’s, and more.