Skip to content
Library to consume and interact with JSON services
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Design goals

  • Be as fast as possible
  • Be simple, yet configurable
  • Include just what you need
  • Don't stomp on object hierarcy (it's a mixin)
  • Lazy load only the objects you need, when you need them

Example usage

class User
  include Voorhees::Resource

  json_service :list, :path => "/users/find.json"

  def messages
    json_request(:class => Message) do |r|
      r.path = "/#{}/messages.json"

users = User.list(:page => 2)

user = users[0]
user.json_attributes      => [:id, :login, :email]
user.raw_json             => {:id => 1, :login => 'test', :email => ''}
user.login                => 'test'
user.messages             => [Message, Message, Message, ...]

See /examples/ directory for more.

A bit more in-depth


Setup global configuration for requests with Voorhees::Config These can all be overridden on individual requests/services

Voorhees::Config.setup do |c|
  c[:base_uri]  = ""
  c[:defaults]  = {:api_version => 2}
  c[:timeout]   = 10
  c[:retries]   = 3

Global options

  • logger: set a logger to use for debug messages, defaults to or RAILS_DEFAULT_LOGGER if it's defined

Request global options

These can be set in the global config and overridden on individual services/requests

  • base_uri: Prepend all paths with this, usually the domain of the service
  • defaults: A hash of default parameters
  • http_method: The Net::HTTP method to use. One of Net::HTTP::Get (default), Net::HTTP::Post, Net::HTTP::Put or Net::HTTP::Delete
  • retries: Number of times to retry if it fails to load data from the service
  • timeout: Number of seconds to wait for the service to send data

Request specific options

These cannot be globally set and can only be defined on individual services/requests

  • hierarchy: Define the class hierarchy for nested data - see below for info
  • parameters: Hash of data to send along with the request, overrides any defaults
  • path: Path to the service. Can be relative if you have a base_uri set.
  • required: Array of required parameters. Raises a Voorhees::ParameterMissingError if a required parameter is not set.

Timeouts and Retries

As well as setting the open_timeout/read_timeout of Net::HTTP, we also wrap each request in a timeout check.

If SystemTimer is installed it will use this, otherwise it falls back on the Timeout library.

If the request fails with a Timeout::Error, or a Errno::ECONNREFUSED, we attept the request again upto the number of retries specified.

For Errno::ECONNREFUSED errors, we also sleep for 1 second to give the service a chance to wake up.

Services and Requests

There are 3 ways to communicate with the service.


This sets up a class method

class User
  include Voorhees::Resource
  json_service :list, :path => "/users.json"

User.list(:page => 3)   =>  [User, User, User, ...] 

By default it assumes you're getting items of the same class, you can override this like so:

json_service :list, :path   => "/users.json",
                    :class  => OtherClass


This is used in instance methods:

class User
  include Voorhees::Resource

  def friends
    json_request do |r|
      r.path => "/friends.json"
      r.parameters => {:user_id =>}
end => 2)  => [User, User]

Like json_service, by default it assumes you're getting items of the same class, you can override this like so:

def messages
  json_request(:class => Message) do |r|
    r.path        = "/messages.json"
    r.parameters  = {:user_id =>}        
end  => [Message, Message, ...]

By default a json_request call will convert the JSON to objects, you can make it return something else by setting the :returning property like so:

json_request(:returning => :raw) do |r|

The returning property can be set to the following:

  • :raw => the raw JSON response as a string
  • :json => the JSON parsed to a ruby hash (through JSON.parse)
  • :response => the Voorhees::Response object
  • :objects => casts the JSON into objects (the default)


Both json_service and json_request create Voorhees::Request objects to do their bidding.

If you like you can use this yourself directly.

This sets up a request identical to the json_request messages example above:

request =
request.path        = "/messages.json"
request.parameters  = {:user_id =>} 

To perform the HTTP request (returning a Voorhees::Response object):

response = request.perform

You can now get at the parsed JSON, or convert them to objects:

response.json       => [{id: 5, subject: "Test", ... }, ...]
response.to_objects => [Message, Message, Message, ...]

Object Hierarchies

Say you have a service which responds with a list of users in the following format:


  "name":"Bobby Tables",
    "street":"24 Monkey Close",

You can define a service to consume this as follows:

class User
  include Voorhees::Resource
  json_service :list, :path => ""

Calling User.list will return a list of User instances.

users = User.list
users[0].name => ""

However, what about the address? It just returns as a Hash of parsed JSON:

users[0].address => {"street":"24 Monkey Close", "city":... }

If you have an Address class you'd like to use, you can tell it like so:

json_service :list, :path      => "",
                    :hierarchy => {:address => Address}

You can nest hierarchies to an infinite depth like so:

json_service :list, :path      => "",
                    :hierarchy => {:address => [Address, {:coords => LatLon}]}

Instead of the class name, you can also just use a symbol:

json_service :list, :path      => "",
                    :hierarchy => {:address => [:address, {:coords => :lat_lon}]}

With that we can now do:

users = User.list
users[0].name               => "Bobby Tables"
users[0]    => "Somewhere"
users[0] => 52.9876


  • A JSON library which supports JSON.parse
  • ActiveSupport
  • SystemTimer - falls back on Timer if it's not available


The ideas and design came from discussions when refactoring LVS::JSONService the original of which was developed by Andy Jeffries for use at LVS

Much discussion with John Cinnamond and Jason Lee


Copyright (c) 2009 Richard Livsey. See LICENSE for details.

Something went wrong with that request. Please try again.