Voorhees
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(Message) do |r|
r.path = "/#{self.id}/messages.json"
end
end
end
user = User.get(1)
user.json_attributes => [:id, :login, :email]
user.raw_json => {:id => 1, :login => 'test', :email => '[email protected]'}
user.login => 'test'
user.login = 'new login'
user.login => 'new login'
user.messages => [Message, Message, Message, ...]
User.list(:filter => 'xxx') => [User, User, User, ...]
User.list(:blah => false) => raises ParameterRequiredException
etc...
See /examples/ directory for more.
A bit more in-depth
Configuration
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] = "http://api.example.com/json"
c[:required] = [:something]
c[:defaults] = {:api_version => 2}
c[:timeout] = 10
c[:retries] = 3
end
System options
- logger: set a logger to use for debug messages, defaults to Logger.new(STDOUT) or RAILS_DEFAULT_LOGGER if it's defined
Request options
- base_uri: Prepend all paths with this, usually the domain of the service
- defaults: A hash of default parameters
- hierarchy: Define the class hierarchy for nested data - see below for info
- http_method: The Net::HTTP method to use. One of Net::HTTP::Get (default), Net::HTTP::Post, Net::HTTP::Put or Net::HTTP::Delete
- 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.
- 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
Services and Requests
There are 3 ways to communicate with the service.
json_service
This sets up a class method
class User
include Voorhees::Resource
json_service :list, :path => "/users.json"
end
User.list(:page => 3) => [User, User, User, ...]
json_request
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 => self.id}
end
end
end
User.new.friends(:limit => 2) => [User, User]
By default it assumes you're getting items of the same class, you can override this like so:
def messages
json_request(Message) do |r|
r.path => "/messages.json"
r.parameters => {:user_id => self.id}
end
end
User.new.messages => [Message, Message, ...]
Voorhees::Request
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 = Voorhees::Request.new(Message)
request.path = "/messages.json"
request.parameters => {:user_id => self.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:
curl http://example.com/users.json
[{
"email":"[email protected]",
"username":"btables",
"name":"Bobby Tables",
"id":1,
"address":{
"street":"24 Monkey Close",
"city":"Somesville",
"country":"Somewhere",
"coords":{
"lat":52.9876,
"lon":12.3456
}
}
}]
You can define a service to consume this as follows:
class User
include Voorhees::Resource
json_service :list, :path => "http://example.com/users.json"
end
Calling User.list will return a list of User instances.
users = User.list
users[0].name => "[email protected]"
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 => "http://example.com/users.json",
:hierarchy => {:address => Address}
You can nest hierarchies to an infinite depth like so:
json_service :list, :path => "http://example.com/users.json",
:hierarchy => {:address => [Address, {:coords => LatLon}]}
Instead of the class name, you can also just use a symbol:
json_service :list, :path => "http://example.com/users.json",
:hierarchy => {:address => [:address, {:coords => :lat_lon}]}
With that we can now do:
users = User.list
users[0].name => "Bobby Tables"
users[0].address.country => "Somewhere"
users[0].address.coords.lat => 52.9876
Thanks
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
Copyright (c) 2009 Richard Livsey. See LICENSE for details.