HTTP Services

Koala 1.2beta and later

For 1.1 and earlier (including migration paths to 1.2beta options), see below.

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.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 (:typheous, :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

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.

:faraday_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.faraday_options will be used with every request. Any options passed to an individual request will take precedence over global settings.

Koala.http_service.faraday_options = {
  :beta => true,
  :ssl => {
    :ca_file => file,
    :verify => true
  }
  # etc
}

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})

: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 — though Facebook is moving toward 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 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 SSL configuration, see also this Faraday wiki page.

If you were using the various HTTP options provided in Koala 1.1 and earlier, please look below for migration information (coming soon).

Koala 1.1 and earlier

Out of the box Koala supports two services to handle the HTTP requests going to and from Facebook’s servers: Net::HTTP and Typhoeus. Both of these services are defined in lib/http_services.rb. By default, Koala will try use Typhoeus. If it is not installed or just not available, Koala will use the Net::HTTP-based service instead.

To force Koala to use one service or another, you can run the following line before using Koala anywhere in your code:

Koala.http_service = NetHTTPService # or TyphoeusService

Migration to 1.2: set Faraday.default_adapter as described above. In 1.2beta1 and later, setting Koala.http_service = NetHTTPService or TyphoeusService sets the default adapter automatically (be aware: this will affect other gems using Faraday as well).

Global HTTP Options

These options can be set on the http service, and will be applied to every request. Unless specified, they can be used with either service.

:proxy

Set this to the URL of a proxy server you wish the Net::HTTP request to go through.

Koala.http_service.proxy = "http://my.proxy.com"

Migration to 1.2: use Koala::HTTPService.faraday_options[:proxy]. (The old syntax will be supported with a deprecation warning.)

:timeout

Sets the timeout for Typhoeus or Net::HTTP. For the latter, we set both the open_timeout and read_timeout attributes (see http://www.ensta-paristech.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/http/rdoc/classes/Net/HTTP.html for more details).

Koala.http_service.timeout = 10

Migration path: use Koala::HTTPService.faraday_options[:timeout]. You can now set :open_timeout (connect_timeout for Typhoeus) if you want to control the two values separately. (The old syntax will be supported with a deprecation warning.)

:always_use_ssl

Only requests to the Facebook servers that pass an access token must use HTTPS. If you would like to use HTTPS even for calls that do not use access tokens (like getting a person’s public profile information), you can set the always_use_ssl class attribute to true in both the NetHTTPService and TyphoeusService classes.

Koala.http_service.always_use_ssl = true

Migration to 1.2: use Koala::HTTPService.faraday_options[:use_ssl]. (The old syntax will be supported with a deprecation warning.)

:ca_file, :ca_path

You may find it necessary to specify the certificate file or path to avoid OpenSSL errors. For more information, see http://martinottenwaelter.fr/2010/12/ruby19-and-the-ssl-error/ (thanks to Nitin Pande for his help with this). These options can also be provided on a per-request basis.

# Ubuntu
Koala.http_service.ca_path = '/etc/ssl/certs'
# Mac OS X 
Koala.http_service.ca_file = '/opt/local/share/curl/curl-ca-bundle.crt'

Migration to 1.2: use Koala::HTTPService.faraday_options[:ssl] = {:ca_file => file, :ca_path => y}. (The old syntax will be supported with a deprecation warning.)

:verify_mode

Net::HTTP only
p. When using Net::HTTP, you may want to change the default SSL verification mode (OpenSSL::SSL::VERIFY_PEER), for instance to disable verification (not recommended for production). This option can also be provided on a per-request basis.

Koala.http_service.verify_mode = OpenSSL::SSL::VERIFY_PEER

Migration to 1.2: use Koala::HTTPService.faraday_options[:ssl] = {:verify_mode => mode}. (The old syntax will be supported with a deprecation warning.)

Per-request HTTP Options

All Graph and REST API methods take an optional hash of parameters that get directly forwarded to the HTTP service to be used when issuing the appropriate HTTP request. The following is a description of all options that can be supplied. Note that the option is supported by both the NetHTTPService and TyphoeusService (pre-1.2beta) unless noted otherwise.

: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})

Migration to 1.2: no change. This option can be passed on a per-request basis exactly as before.

:use_ssl

If set to true, uses SSL for this particular request, regardless of the type of request. (By default, requests without access tokens are done over http, and those with tokens are done over https.)

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

Migration to 1.2: no change. This option can be passed on a per-request basis exactly as before.

:proxy

NetHTTPService only
Set this to the URL of a proxy server you wish the Net::HTTP request to go through.

# Uses http://my.proxy.com as a proxy
@graph.get_object('me', {}, {:proxy => "http://my.proxy.com"})

Migration to 1.2: no change. This option can be passed on a per-request basis exactly as before.

:timeout

NetHTTPService only
Sets the Net::HTTP open_timeout and read_timeout attributes to the given value (see http://www.ensta-paristech.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/http/rdoc/classes/Net/HTTP.html for more details).

# Sets the Net::HTTP read_timeout and open_timeout to 10 seconds
@graph.get_object('me', {}, {:timeout => 10})

Migration path: no change. This option can be passed on a per-request basis exactly as before. (Note that you can now specify open_timeout separately if desired.)

:typhoeus_options

TyphoeusService only
Use this to pass any options directly to Typhoeus#send.

# Sends the options in typh_options to Typhoeus#send
@graph.get_object('me', {}, {:typhoeus_options => typh_options})

Migration path: include any options for Typhoeus directly in your http_options hash. (The old syntax will be supported with a deprecation warning.)

:ca_file, :ca_path, :verify_mode

See descriptions above for these keys.

Migration path: include these options in your http_options hash as :ssl => {:ca_file => file, :ca_path => path, :verify_mode => mode}. (The old syntax will be supported with a deprecation warning.)

---

A Note On Typhoeus

When using the Typhoeus service, if you want to upload pictures or videos stored as IOs or other non-file objects, Koala will (by necessity) use the Net::HTTP service for that operation. If you’ve set global options on the Typhoeus service, you’ll need to also set them on Net::HTTP for this case.

This behavior is pre-1.2beta only_! Now that Facebook allows you to upload photos by providing a URL, the primary use case for this mechanism (uploading to Facebook from an IO pointing to a remote file) is no longer relevant. Koala will no longer automatically support such uploads. (You can, however, manage them by changing faradaymiddleware to use Net::HTTP before making such requests.)