RESTHome

Simple wrapper class generator for consuming RESTful web services

RESTful Example

RESTHome's are used to communicate to RESTful Web Services.

Let's say you are working with B2B.dev. They provide a simple RESTful API for interacting with customer data.

API looks like

GET    http://api.b2b.dev/customers.json      - list of your customers
GET    http://api.b2b.dev/customers/<id>.json - customer data
PUT    http://api.b2b.dev/customers/<id>.json - edit customer data
DELETE http://api.b2b.dev/customers/<id>.json - delete customer
POST   http://api.b2b.dev/customers.json      - create a new customer

JSON response looks like {'customer': {'id': 99, 'first_name': 'Joe', 'last_name': 'Smith'}}

Create a simple RESTHome service to interact with B2B.dev api.

class B2BService < RESTHome
  rest :customer, :customers, '/customers.json'

  def initialize(api_key)
    self.base_uri = 'http://api.b2b.dev'
    self.basic_auth = {:username => api_key, :password => 'x'}
  end
end

service = B2BService.new 'XXXXX'
service.customers # returns an array of customers
customer = service.customer 99 # returns the data for customer 99, i.e. {:first_name => 'Joe', :last_name => 'Smith'}
service.edit_customer 99, :first_name => 'Joesph', :last_name => 'Smithie' # edits customer 99
service.delete_customer 99 # deletes customer 99
service.create_customer :first_name => 'John', :last_name => 'Doe' # creates a new customer

Lorem Lipsum Example

Create a simple lorem lipsum generator, using www.lipsum.com.

lipsum = RESTHome.new
lipsum.base_uri = 'http://www.lipsum.com'
lipsum.route :generate, '/feed/json', :method => :post
words = lipsum.generate(:what => 'words', :amount => 20) do |res|
  res['feed']['lipsum']
end

class LoremLipsumService < RESTHome
  base_uri 'http://www.lipsum.com'

  route :generate, '/feed/json', :method => :post do |res|
    res['feed']['lipsum']
  end
end

service = LoremLipsumService.new
words = service.generate(:what => 'words', :amount => 20)

LastFM Example query arguments

How to replace query parameters with function arguments.

class LastFmWebService < RESTHome
  base_uri 'http://ws.audioscrobbler.com'

  namespace '/2.0' do
    route :track, '/', :query => {'method' => 'track.getinfo', 'artist' => :arg1, 'track' => :arg2}, :resource => 'track'
  end

  def initialize(api_key)
    @api_key = api_key
  end

  def build_options!(options)
    options[:query] ||= {}
    options[:query]['format'] = 'json'
    options[:query]['api_key'] = @api_key
  end
end

service = LastFmWebService.new 'xxxxxxxxx'
service.track 'cher', 'believe'

Twilio Example send SMS message

TwilioWebService.service.send_sms_message '5551112222', 'Verification Code: 2121'

Amazon Simple Email Service (SES)

How to replace body parameters with function arguments. Complete Amazon SES model in examples folder.

require 'digest/sha2'
require 'base64'

class AmazonSESService < RESTHome
  base_uri 'https://email.us-east-1.amazonaws.com'

  @@digest256 = OpenSSL::Digest::Digest.new("sha256")

  route :verify_email_address, '/', :body => {'Action' => 'VerifyEmailAddress', 'EmailAddress' => :arg1}, :method => :post, :expected_status => 200, :no_body => true do |res|
    res['VerifyEmailAddressResponse']
  end

  def initialize(access_key, secret)
    @access_key = access_key
    @secret = secret
  end

  def build_options!(options)
    date = Time.now.getutc.httpdate
    options[:headers] ||= {}
    options[:headers]['Date'] = date
    options[:headers]['X-Amzn-Authorization'] = "AWS3-HTTPS AWSAccessKeyId=#{@access_key},Algorithm=HMACSHA256,Signature=#{AmazonSESService.sign_request(@secret, date)}"
  end

  def self.sign_request(secret, date)
    Base64.encode64(OpenSSL::HMAC.digest(@@digest256, secret, date)).gsub("\n","")
  end
end

service = AmazonSESService.new :access_key_id => 'my-access-key', :secret_access_key => 'it-s-a-secret'
service.verify_email_address 'test@test.dev'

Contributing to RESTHome

Copyright © 2010 Cykod LLC. See LICENSE.txt for further details.