Library to consume and interact with JSON services
MIT License
class User
include Voorhees::Resource
json_service :list, :path => "/users/find.json"
def messages
json_request(:class => Message) do |r|
r.path = "/#{self.id}/messages.json"
end
end
end
users = User.list(:page => 2)
user = users[0]
user.json_attributes => [:id, :login, :email]
user.raw_json => {:id => 1, :login => 'test', :email => '[email protected]'}
user.login => 'test'
user.messages => [Message, Message, Message, ...]
See /examples/ directory for more.
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[:defaults] = {:api_version => 2}
c[:timeout] = 10
c[:retries] = 3
end
These can be set in the global config and overridden on individual services/requests
These cannot be globally set and can only be defined on individual services/requests
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.
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"
end
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 => self.id}
end
end
end
User.new.friends(:limit => 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 => self.id}
end
end
User.new.messages => [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|
...
end
The returning property can be set to the following:
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, ...]
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
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.