arsduo/koala: a Ruby Facebook library whose README is a time capsule

Four stated goals, and which of them still hold

The README opens with four goals, and reading them in order tells you what kind of library this is.

Lightweight is the first goal, and the stated standard is instructive: as light and simple as Facebook's own libraries, providing API accessors and returning simple JSON. That is a specific and unusual ambition. Rather than wrapping responses in model objects, Koala hands back plain Ruby hashes, which means you decide how much structure your application wants.

Fast is second, and the mechanism is documented. Out of the box the library uses Facebook's faster read-only servers when possible, and uses the Typhoeus gem to make snappy requests. The first of those is a server-side routing decision that has aged with the API, and the second is a real choice you inherit as a dependency.

Flexible is third. The README's version of flexibility is runtime support, and this is where the README stops matching reality. It says the library supports all currently-supported Ruby versions, then names them: MRI 2.1 to 2.4, plus JRuby and Rubinius. Ruby 2.4 reached end of life years before this repository's last push, and Rubinius has been dormant for longer than that. The claim is about the range of Ruby implementations the code targets rather than about what a Ruby user calls currently supported, but a reader arriving today will read it the other way.

Tested is fourth, with complete coverage runnable against mocked responses or live servers, and a mention of Travis CI as the continuous integration host. The testing claim is the one you can check yourself, and the CI claim is the one that has visibly aged, since the README's badge still points at travis-ci.org while the repository tree contains a GitHub Actions directory.

Installation, global configuration, and the threadsafe warning

In a Bundler-managed project the dependency is one line:

gem "koala"

Outside Bundler, the README gives a single command with a version manager prefix left as a choice:

[sudo|rvm] gem install koala

Configuration is global by default, and the README is explicit about the reason: most applications need only one application configuration, so requiring that value on every call would be noise. The block looks like this:

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

Read the comment above it carefully. In a Rails application this belongs in an initializer, which means it runs once at boot and mutates a shared object. The README immediately follows the block with a note that this is not currently threadsafe, and invites pull requests that support both threaded and non-threaded configuration.

That is the most consequential line in the README, and it is easy to skim past because it is formatted as a parenthetical. A global mutable configuration object mutated at boot is fine for a single-process application that makes its Facebook calls from one thread. It is a genuine hazard for an application running a threaded server such as Puma with workers, where a request handler that needs a different token has no supported way to ask for one. Per-call access tokens are supported by passing one to the constructor, which is the path a threaded application has to take, and the README's global-config default pushes you the other way.

The comment also points at the configuration class for more options, including sending requests through your own proxy servers, which is worth knowing before you conclude that an outbound proxy is a deployment problem rather than a configuration setting.

Object, connection, and collection calls

The Graph API section is where the library's shape becomes obvious. Getting a token is described as a browser step in Facebook's Graph API Explorer, and everything after that is Ruby:

@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 methods, three shapes: fetch one node, fetch a connection, write to a connection. The third-part path form is there too, so you can reach nested connections with a string containing slashes. What makes the API pleasant is that it stops at the request boundary and returns hashes, so there is no mapping layer to learn.

The connection return type is the useful part. When a call returns an array of results, such as a connection or a search, you get a GraphCollection object, which subclasses Array and therefore works with the ordinary enumerable methods:

feed = @graph.get_connections("me", "feed")
feed.each {|f| do_something_with_item(f) }
next_feed = feed.next_page

The convenience that earns its keep is `next_page_params`. It returns the path and arguments needed to fetch the next page, which is exactly what you want when paging state has to survive across browser requests, and it is the kind of detail that separates a wrapper from a pass-through.

One caution about these examples. They are written against an early generation of Facebook's API, and the README itself shows the version pinned at v2.0, whether set globally or per request. Facebook versions its API and deprecates generations on a schedule, so whether any particular connection in these examples still resolves is a question for Facebook's current reference documentation rather than for this repository. Treat the method names as the stable part and the paths as the part to verify.

Batching and post-processing blocks

The batch support is the strongest argument for using a wrapper at all, because doing it by hand means hand-building a multipart document with an explicit depends-on chain.

@graph.batch do |batch_api|
  batch_api.get_object('me')
  batch_api.put_wall_post('Making a post in a batch.')
end

The block yields a batch API, calls inside it accumulate, and the return value is an array of results that looks as though the calls had been made individually. Reading a batch response back positionally is unpleasant, which is what the second feature addresses.

Every Graph API method accepts a block that post-processes the result. The README gives two reasons, and the second is the interesting one. The first is reshaping: block the object, take one key out of it. The second is consuming in place, which matters specifically in the batch case, because instead of pulling result number two out of an array you assign directly while the results are being read:

@graph.batch do |batch_api|
  batch_api.get_object('me')                {|me|     self.about_me = me }
  batch_api.get_connections('me', 'photos') {|photos| self.photos   = photos }
end

That is a small design decision with a large effect on batch code readability, and it is the kind of thing that comes from someone who has written the awkward version first.

The API versioning story completes the picture. The README says that if you do not specify a version, Facebook defaults to the oldest version your app is allowed to use, and shows both the global and per-request forms. Pinning per request is the better habit, since it makes the version visible at the call site and lets two calls in one application target different generations during a migration.

App tokens, signed requests, and realtime updates

The app access token path is two lines, and it is the piece most applications need beyond a user session:

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

The described purpose is subscriptions and certain other requests that do not need a user session. Signed request parsing is the other method the README highlights, for anyone receiving a signed payload from Facebook and needing to verify it rather than trust it.

Realtime updates are the third area, and the README is refreshingly honest about the division of labour. It says reaching out to Facebook is a pain and suggests letting Facebook reach out instead, then links Facebook's own realtime documentation for which objects can be subscribed to and what the limitations are. In other words, the library wraps the subscription mechanics and hands the eligibility question back to Facebook.

@updates = Koala::Facebook::RealtimeUpdates.new(app_id: app_id, secret: secret

The repository description adds two more areas the README does not detail: test users and OAuth validation. The description also names the Marketing API and the Atlas API. Atlas is the entry that deserves a note, because nothing in the repository explains what Atlas support means, and the project's declared homepage points at Facebook's developer documentation rather than at any page about Koala itself. A homepage field that points upstream at the API vendor tells you nothing about the library's health, its documentation or its maintenance state, so judge this project from its README and its changelog instead.

Both facts sit side by side without a winner. The description claims coverage of three APIs, the README details one of them in depth, and the third is not explained anywhere in the files. How to judge: grep the repository for the marketing and atlas namespaces, and if you find modules for them, read their specs, because an implemented module and a working integration against today's version of that API are different claims.

An MRI 2.1 to 2.4 support claim against a 2026 push date

Set the two facts next to each other. The README says the library supports all currently-supported Ruby versions and names MRI 2.1 to 2.4. The repository's last push was on 2026-09-28 and it is not archived. Ruby 2.1 and 2.2 have not been maintained for close to a decade, and 2.4 followed them out of support years ago, so the sentence describes a range of Ruby implementations the code is written to work on, not a live support statement.

The same two facts point in opposite directions about what to check. A push date that recent says somebody is committing code, which is not the same as somebody is reviewing the API surface or the dependency set. The README's own continuous integration claim is the more dated signal: the badge links to travis-ci.org, and the README names Travis CI as the host, while a GitHub Actions directory sits in the repository tree. Travis CI for open source has been a paid service for years, so a badge pointing there is a leftover rather than a working status indicator.

For a reader deciding whether to depend on this, the practical checks are concrete. Read `changelog.md` at the root, which is the only version narrative in the project, since there are no GitHub releases to read. Read `koala.gemspec` for the dependency constraints, because the README's Ruby range is a claim about the code and the gemspec is a claim about the install. And look at `spec/` rather than the badge, since a complete test suite that runs against mocked responses is the one coverage claim in the README you can inspect directly.

On licensing, the repository is MIT with a LICENSE file at the root and a Manifest file beside it, which is the packaging convention from Ruby projects of the era this library comes from. That grant places no restriction on commercial use or on redistribution, so licensing is not a reason to hesitate. Everything else above is a question about the API's current state, not about permission to use the code.

Editorial conclusion

Koala is worth reading as a model of what a thin API wrapper should look like, and worth being careful about as a dependency. Every convenience it adds, object and connection helpers, paging through a collection, batching, post-processing blocks that let you reshape a result, is the kind of thing you would otherwise write badly yourself. What you inherit is a README written against an early generation of the Graph API, a claim to support Ruby 2.1 through 2.4, and a global configuration object the README itself flags as not threadsafe. Before depending on it, open Facebook's current Graph API reference and confirm the two or three calls you actually need still exist, then check the changelog at the repository root, which is the only version history in the project.

Frequently asked questions

Official sources

1. arsduo/koala on GitHub
2. Issues
3. License: MIT
4. Project website
5. README