[opensourcedex]

koala is a free, open source social networking project written in Ruby and released under MIT. It has 3,568 GitHub stars, 456 forks and 45 open issues, and was last pushed 11 months ago. On this registry it ranks #14 of 44 tracked projects in Social Networking, with 5 head-to-head comparisons available.

What is koala?

What it is

Koala is a lightweight Ruby library for Facebook APIs. It supports the Graph API, the Marketing API, the Atlas API, realtime updates, test users, and OAuth validation. It lives in the Ruby and Ruby on Rails ecosystem and provides API accessors that return simple JSON responses.

The project solves the concrete problem of giving Ruby applications programmatic access to Facebook services without hand-writing request handling, token validation, batch requests, photo uploads, and API versioning. It uses Facebook's faster read-only servers when possible and can use the Typhoeus gem when available for snappy requests. It supports MRI 2.1 through 2.4, JRuby, and Rubinius, and its tests can run against mocked responses or live Facebook servers.

Key capabilities

  • Koala provides Graph API methods such as get_object, get_connections, put_connections, batch requests, photo uploads, three-part queries, and Timeline API actions.
  • Koala supports OAuth validation and application configuration through access_token, app_access_token, app_id, and app_secret.
  • Koala supports appsecret parameters that tie access tokens to the application secret.
  • Koala supports Facebook API versioning globally through Koala.config.api_version or on a per-request basis.
  • Koala includes support for the Marketing API, the Atlas API, realtime updates, and test users.
  • Koala can be configured for global settings, including sending requests through proxy servers.

Who uses it and how

  • Rails developers can place Koala configuration in config/initializers/koala.rb, so applications avoid passing credentials on every request.
  • Applications that read user data can create a Koala::Facebook::API object with an access token and call get_object("me") or get_connections("me", "friends").
  • Applications that publish content can call put_connections("me", "feed", message: "I am writing on my wall!") to write to the user's feed.
  • Applications that pass an appsecret parameter can initialize Koala::Facebook::API.new(access_token, app_secret) for extra security.
  • Developers can test Koala against mocked responses or live Facebook servers.

Getting started

Install Koala by adding gem "koala" to a Bundler Gemfile, or by running gem install koala with sudo or rvm. After installation, require koala, configure credentials, and create a Koala::Facebook::API object.

When to use it — and when not to

Use Koala when a Ruby or Ruby on Rails application needs direct access to Facebook's Graph, Marketing, and Atlas APIs without writing low-level request code. Do not use Koala when you need a hosted service, a non-Ruby client, or threadsafe global configuration, because the README says global configuration is not currently threadsafe and lists MRI 2.1 through 2.4 support. Teams must still manage Facebook app credentials, access tokens, and application deployment.

project readme (upstream, from github) — read inline

Koala Version Build Status Code Climate Code Coverage

Koala is a Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the Marketing API, the Atlas API, realtime updates, test users, and OAuth validation. We wrote Koala with four goals:

  • Lightweight: Koala should be as light and simple as Facebook’s own libraries, providing API accessors and returning simple JSON.
  • Fast: Koala should, out of the box, be quick. Out of the box, we use Facebook's faster read-only servers when possible and if available, the Typhoeus gem to make snappy Facebook requests. Of course, that brings us to our next topic:
  • Flexible: Koala should be useful to everyone, regardless of their current configuration. We support all currently-supported Ruby versions (MRI 2.1-2.4) and Koala should work on JRuby and Rubinius.
  • Tested: Koala should have complete test coverage, so you can rely on it. Our test coverage is complete and can be run against either mocked responses or the live Facebook servers; we're also on Travis CI.

Found a bug? Interested in contributing? Check out the Maintenance section below!

Installation

Koala 3.0 is out! There should be no significant changes for most users. If you encounter any problems, please file an issue and I'll take a look.

In Bundler:

gem "koala"

Otherwise:

[sudo|rvm] gem install koala

Configuration

Most applications will only use one application configuration. Rather than having to provide that value every time, you can configure Koala to use global settings:

# In Rails, you could put this in config/initializers/koala.rb
Koala.configure do |config|
  config.access_token = MY_TOKEN
  config.app_access_token = MY_APP_ACCESS_TOKEN
  config.app_id = MY_APP_ID
  config.app_secret = MY_APP_SECRET
  # See Koala::Configuration for more options, including details on how to send requests through
  # your own proxy servers.
end

Note: this is not currently threadsafe. (PRs welcome as long as they support both threaded and non-threaded configuration.)

Graph API

The Graph API is the interface to Facebook's data. Using it with Koala is quite straightforward. First, you'll need an access token, which you can get through Facebook's Graph API Explorer (click on 'Get Access Token').

Then, go exploring:

require 'koala'

# access_token and other values aren't required if you set the defaults as described above
@graph = Koala::Facebook::API.new(access_token)

profile = @graph.get_object("me")
friends = @graph.get_connections("me", "friends")
@graph.put_connections("me", "feed", message: "I am writing on my wall!")

# Three-part queries are easy too!
@graph.get_connections("me", "mutualfriends/#{friend_id}")

# You can use the Timeline API:
# (see https://developers.facebook.com/docs/beta/opengraph/tutorial/)
@graph.put_connections("me", "namespace:action", object: object_url)

# For extra security (recommended), you can provide an appsecret parameter,
# tying your access tokens to your app secret.
# (See https://developers.facebook.com/docs/reference/api/securing-graph-api/

# You may need to turn on 'Require proof on all calls' in the advanced section
# of your app's settings when doing this.
@graph = Koala::Facebook::API.new(access_token, app_secret)

# Facebook is now versioning their API. # If you don't specify a version, Facebook
# will default to the oldest version your app is allowed to use.
# See https://developers.facebook.com/docs/apps/versions for more information.
#
# You can specify version either globally:
Koala.config.api_version = "v2.0"
# or on a per-request basis
@graph.get_object("me", {}, api_version: "v2.0")

The response of most requests is the JSON data returned from the Facebook servers as a Hash.

When retrieving data that returns an array of results (for example, when calling API#get_connections or API#search) a GraphCollection object will be returned, which makes it easy to page through the results:

# Returns the feed items for the currently logged-in user as a GraphCollection
feed = @graph.get_connections("me", "feed")
feed.each {|f| do_something_with_item(f) } # it's a subclass of Array
next_feed = feed.next_page

# You can also get an array describing the URL for the next page: [path, arguments]
# This is useful for storing page state across multiple browser requests
next_page_params = feed.next_page_params
page = @graph.get_page(next_page_params)

You can also make multiple calls at once using Facebook's batch API:

# Returns an array of results as if they were called non-batch
@graph.batch do |batch_api|
  batch_api.get_object('me')
  batch_api.put_wall_post('Making a post in a batch.')
end

You can pass a "post-processing" block to each of Koala's Graph API methods. This is handy for two reasons:

  1. You can modify the result returned by the Graph API method:

     education = @graph.get_object("me") { |data| data['education'] }
 # returned value only contains the "education" portion of the profile

  2. You can consume the data in place which is particularly useful in the batch case, so you don't have to pull the results apart from a long list of array entries:

     @graph.batch do |batch_api|
   # Assuming you have database fields "about_me" and "photos"
   batch_api.get_object('me')                {|me|     self.about_me = me }
   batch_api.get_connections('me', 'photos') {|photos| self.photos   = photos }
 end

Check out the wiki for more details and examples.

App Access Tokens

You get your application's own access token, which can be used without a user session for subscriptions and certain other requests:

@oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
@oauth.get_app_access_token

For those building apps on Facebook, parsing signed requests is simple:

@oauth.parse_signed_request(signed_request_string)

The OAuth class has additional methods that may occasionally be useful.

Real-time Updates

Sometimes, reaching out to Facebook is a pain -- let it reach out to you instead. The Graph API allows your application to subscribe to real-time updates for certain objects in the graph; check the official Facebook documentation for more details on what objects you can subscribe to and what limitations may apply.

Koala makes it easy to interact with your applications using the RealtimeUpdates class:

# This class also supports the defaults as described above
@updates = Koala::Facebook::RealtimeUpdates.new(app_id: app_id, secret: secret)

You can do just about anything with your real-time update subscriptions using the RealtimeUpdates class:

# Add/modify a subscription to updates for when the first_name or last_name fields of any of your users is changed
@updates.subscribe("user", "first_name, last_name", callback_url, verify_token)

# Get an array of your current subscriptions (one hash for each object you've subscribed to)
@updates.list_subscriptions

# Unsubscribe from updates for an object
@updates.unsubscribe("user")

And to top it all off, RealtimeUpdates provides a static method to respond to Facebook servers' verification of your callback URLs:

# Returns the hub.challenge parameter in params if the verify token in params matches verify_token
Koala::Facebook::RealtimeUpdates.meet_challenge(params, your_verify_token)

For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.

Rate limits

We support Facebook rate limit informations as defined here: https://developers.facebook.com/docs/graph-api/overview/rate-limiting/

The information is available either via the Facebook::APIError:

error.fb_buc_usage
error.fb_ada_usage
error.fb_app_usage

Or with the rate_limit_hook:

## App level configuration

Koala.configure do |config|
  config.rate_limit_hook = ->(limits) { 
    limits["x-app-usage"] # {"call_count"=>0, "total_cputime"=>0, "total_time"=>0}
    limits["x-ad-account-usage"] # {"acc_id_util_pct"=>9.67}
    limits["x-business-use-case-usage"] # {"123456789012345"=>[{"type"=>"messenger", "call_count"=>1, "total_cputime"=>1, "total_time"=>1, "es

readme truncated — read the full docs on github

Frequently asked questions

Is koala free to use?

koala is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does koala do?

A lightweight Facebook library supporting the Graph, Marketing, and Atlas APIs, realtime updates, test users, and OAuth.

What is koala written in?

koala is primarily written in Ruby. Its source is publicly available at https://github.com/arsduo/koala, and it has 3,568 GitHub stars.