HTTP Services

Koala uses Faraday to make requests to Facebook. Faraday is a modular framework, patterned on Rack, which makes it easy to control and customize how Ruby makes HTTP requests; Koala, in turn, allows you to take advantage of Faraday’s configuration options to tailor requests to your needs.

If you’d like further customize how Koala handles requests, see Extensions.

Global HTTP Options

These options can be set on Koala.http_service (which outside of mock testing points to Koala::HTTPService), and will be applied to every request.

:faraday_middleware

With Faraday, you can build a stack of handlers that can massage, prepare, and process HTTP requests. You do this by passing a block to Faraday.new, building up your middleware stack. By default, Koala uses the following stack:

DEFAULT_MIDDLEWARE = Proc.new do |builder|
  builder.request :multipart
  builder.use Koala::MultipartRequest
  builder.request :url_encoded
  builder.adapter Faraday.default_adapter
end

This stack, by default, has three parts:

• multipart: detects if you’re uploading files, and if so turns the request into a properly formatted multipart post
• url_encoded: properly convert request params to “www-form-urlencoded”
• default_adapter: uses whichever HTTP library you define as the default to make the request (:typhoeus, :net_http, :etc)

If you simply want to use a specific HTTP library, you can specify that in your application initialization, and Koala will automatically use it:

Faraday.default_adapter = :typhoeus
# for persistent connections using Faraday 0.8 and the net-http-persistent gem
Faraday.default_adapter = :net_http_persistent

If, on the other hand, you want to set up a custom middleware stack, you can provide a custom block:

Koala.http_service.faraday_middleware = Proc.new do |builder|
  builder.request :json
  builder.response :my_logging_middleware

  # remember: the default middleware and an adapter are necessary for Koala to work properly!
  builder.request :multipart
  builder.request :url_encoded
  builder.adapter Faraday.default_adapter
end

Koala will then use that when creating Faraday connections.

:http_options

You can specify http_options with every request, which let you control such things as SSL certificate configuration, proxies and timeouts, whether to use Facebook’s beta tier, etc. Most of the time, these are settings that you want used every time, and so you can set them at a global level. (This consolidates and replaces the various settings — :proxy, :timeout, etc. — previously available in Koala.)

The setting hash you provide with Koala.http_service.http_options will be used with every request. Any options passed to an individual request will take precedence over global settings.

Koala.http_service.http_options = {
  # Koala options
  :beta => true, # use FB beta layer
  # Faraday options
  :ssl => {
    # see below for info on ca_path and ca_file
    :ca_file => file,
    :ca_path => path,
    # SSL verify defaults to true unless you explicitly set it to false
    :verify => true
  },
  # see below for links to info on Faraday options
}

See the next section for available options.

HTTP Options for Koala

All options can be used either per-request or globally.

:beta

If set to true, the request is sent to the beta version of whichever API (Graph or REST) that you are using. Useful for ensuring your application won’t break as changes are released.

# Sends a request to http://beta.graph.facebook.com 
@graph.get_object('me', {}, {:beta => true})

:format

:format set to :json will send POST/PUT requests as JSON (content type set to application/json and request body rendered with `.to_json`), which is useful for some Facebook endpoints.

:preserve_form_arguments

For certain APIs (such as the Ads API, social_prefs and view_tags), you may want to pass array arguments straight through to the API rather than having them be reformatted as comma-separated strings. You can provide preserve_form_arguments: true on a global or per-request basis to prevent Koala from reformatting those arrays into a format Facebook won’t understand.

:use_ssl

If set to true, Koala will make all requests or an individual request (depending on where it’s set) via SSL, regardless of the type of request. By default, requests without access tokens are done over http, and those with tokens are done over https (Facebook has hinted at eventually requiring SSL and tokens for all requests).

# Sends a request to https://graph.facebook.com 
@graph.get_object('me', {}, {:use_ssl => true})

SSL, proxy, timeout, and other Faraday options

Various HTTP For additional options will be available for your HTTP library of choice. Check out the implementation of the relevant adapter for more details.

For instance, as of Faraday 0.9.1, you can set request timeouts like so:

Koala.http_service.http_options = {
  request: {
    timeout: 5,
    open_timeout: 2 # Net::HTTP adapter only
  }
}

(Future version of Faraday may be different, so if this doesn’t work please consult the docs for that gem.)

:ca_file, :ca_path

You may find it necessary to specify the certificate file or path to avoid OpenSSL errors. For more information, see this blog entry (thanks to Nitin Pande for his help with this). These options can also be provided on a per-request basis.

# Ubuntu
(Koala.http_service.http_options[:ssl] ||= {})[:ca_path] = '/etc/ssl/certs'
# Mac OS X 
(Koala.http_service.http_options[:ssl] ||= {})[:ca_file] = '/opt/local/share/curl/curl-ca-bundle.crt'