relax 0.0.1 → 0.0.2

data/README

@@ -1,4 +1,153 @@
-Relax
-=====
+= Relax
 
-A simple library for creating REST consumers.
+Relax is a simple library for creating REST consumers.
+
+When used as a basis for writing REST consumer APIs, it provides a set of
+functionality common to all REST consumers, including:
+
+- building HTTP queries (Relax::Request)
+- issuing HTTP requests (Relax::Service)
+- parsing XML responses (Relax::Response)
+
+
+== Tutorial
+
+This short tutorial will walk you through the basic steps of creating a simple Flickr API that supports a single call to search for photos by tags.
+
+=== Step 1
+
+In the first step we're going to simply include Relax, and define the basis for
+our Service class.
+
+  require 'rubygems'
+  require 'relax'
+
+  module Flickr
+    class Service < Relax::Service
+      ENDPOINT = 'http://api.flickr.com/services/rest/'
+
+      def initialize
+        super(ENDPOINT)
+      end
+    end
+  end
+
+
+=== Step 2
+
+Next we're going to define common Request and Response classes for use
+throughout our API. This gives us a single point to add any shared
+functionality. For Flickr, this means that each request will have a "method"
+parameter, and each response will have a "stat" attribute that will equal "ok"
+when the response comes back without any errors.
+
+  module Flickr
+    class Request < Relax::Request
+      parameter :method
+    end
+
+    class Response < Relax::Response
+      def successful?
+        root[:stat] == 'ok'
+      end
+    end
+  end
+
+While we're at it, we're also going to add a new line to the constructor from
+our service to make sure that our Flickr API key gets passed along with each
+request as well.
+
+  module Flickr
+    class Service < Relax::Service
+      ENDPOINT = 'http://api.flickr.com/services/rest/'
+      
+      def initialize(api_key)
+        super(ENDPOINT)
+        Request[:api_key] = api_key
+      end
+    end
+  end
+
+When we call our Request class as we have here, we're basically setting up a
+value on our request that acts like a template. Each request we create now will
+have the api_key property prepopulated for us.
+
+
+=== Step 3
+
+Next, we're going to need a basic Photo class to represent photos that Flickr
+returns to us.
+
+  module Flickr
+    class Photo < Response
+      parameter :id, :attribute => true, :type => :integer
+      parameter :title, :attribute => true
+    end
+  end
+
+Here we're creating a Response class that extends our Flickr::Response, which
+has two parameters: "id" and "title." By setting the attribute option to true,
+we're telling Relax to look for an attribute by that name on the XML root
+instead of checking for an element by that name. The type options can be used
+to specify what type of data we're expecting the response to give us. The
+default type is string.
+
+
+=== Step 4
+
+Now we arrive at the final piece of the puzzle: a service call module. To keep
+things contained, a Relax best practice is to create a module for each call
+on your service. The one we're creating here is the PhotoSearch module for the
+"flickr.photos.search" call on the Flickr API.
+
+There are three main pieces to every service call module:
+
+1. a Relax::Request object
+2. a Relax::Response object
+3. a call method that calls Relax::Service#call
+
+This module then gets included into the Service class, where the call method
+can be easily utilized.
+
+  module Flickr
+    module PhotoSearch
+      class PhotoSearchRequest < Flickr::Request
+        parameter :per_page
+        parameter :tags
+
+        def initialize(options = {})
+          super
+          @method = 'flickr.photos.search'
+        end
+      end
+
+      class PhotoSearchResponse < Flickr::Response
+        parameter :photos, :element => 'photos/photo', :collection => Photo
+      end
+
+      def search(options = {})
+        call(PhotoSearchRequest.new(options), PhotoSearchResponse)
+      end
+
+      def find_by_tag(tags, options = {})
+        search(options.merge(:tags => tags))
+      end
+    end
+  end
+
+As you can see, we have our request (PhotoSearchRequest), response
+(PhotoSearchResponse), and call method (actually, two in this case: search and
+ find_by_tag). This will get included into our Flickr::Service class, and we
+can use it by calling either of the call methods.
+
+  flickr = Flickr::Service.new(ENV['FLICKR_API_KEY'])
+  relax = flickr.find_by_tag('relax', :per_page => 10)
+
+  if relax.successful?
+    relax.photos.each do |photo|
+      puts "[#{photo.id}] #{photo.title}"
+    end
+  end
+
+This will output the IDs and titles for the first 10 photos on Flickr that have
+the tag "relax."

data/lib/relax/query.rb

@@ -4,7 +4,10 @@ require 'uri'
 require 'relax/symbolic_hash'
 
 module Relax
+  # Query is used to represent the query portion of a URL. It's basically just
+  # a hash, where each key/value pair is a query parameter.
   class Query < SymbolicHash
+    # Converts the Query to a query string for use in a URL.
     def to_s
       keys.sort { |a, b| a.to_s <=> b.to_s }.collect do |key|
         "#{key.to_s}=#{self.class.escape_value(fetch(key))}"
@@ -12,6 +15,7 @@ module Relax
     end
 
     class << self
+      # Parses a URL and returns a Query with its query portion.
       def parse(uri)
         query = uri.query.split('&').inject({}) do |query, parameter|
           key, value = parameter.split('=')
@@ -21,10 +25,12 @@ module Relax
         self.new(query)
       end
 
+      # Escapes a query parameter value.
       def escape_value(value)
         ERB::Util.url_encode(value.to_s).gsub('%20', '+')
       end
 
+      # Unescapes a query parameter value.
       def unescape_value(value)
         URI.unescape(value)
       end
@@ -32,6 +38,7 @@ module Relax
 
     protected
 
+    # Converts each value of the Query to a string as it's added.
     def convert_value(value)
       value.to_s
     end

data/lib/relax/request.rb

@@ -1,6 +1,8 @@
 require 'relax/query'
 
 module Relax
+  # Request is intended to be a parent class for requests passed to
+  # Service#call.
   class Request
     def initialize(options = {})
       self.class.class_variables.each do |variable|
@@ -12,6 +14,7 @@ module Relax
       end
     end
 
+    # Converts this request into a Query object.
     def to_query
       keys.inject(Query.new) do |parameters, key|
         parameters[convert_key(key)] = send(key)
@@ -19,18 +22,23 @@ module Relax
       end
     end
 
+    # Converts this request into a query string for use in a URL.
     def to_s
-      keys.sort { |a, b| a.to_s <=> b.to_s }.collect do |key|
-        "#{key.to_s}=#{ERB::Util.url_encode(send('[]', key).to_s)}"
-      end.join('&')
+      to_query.to_s
     end
 
     class << self
+      # Specifies a parameter to create on the request class.
+      #
+      # Options:
+      # - <tt>:value</tt>: The default value for this parameter.
       def parameter(name, options = {})
         attr_accessor name
         class_variable_set("@@#{name}", options.delete(:value)) if options[:value]
       end
 
+      # Adds a template value to a request class. Equivalent to creating a
+      # parameter with a default value.
       def []=(key, value)
         parameter(key, {:value => value})
       end
@@ -38,10 +46,15 @@ module Relax
 
     protected
 
+    # Returns an array of the parameter names for this request.
     def keys
       instance_variables.collect { |v| v.sub('@', '') }
     end
 
+    # Converts a key when the Request is converted to a query. By default, no
+    # conversion actually takes place, but this method can be overridden by
+    # child classes to perform standard manipulations, such as replacing
+    # underscores.
     def convert_key(key)
       key
     end

data/lib/relax/response.rb

@@ -4,9 +4,18 @@ require 'hpricot'
 require 'date'
 
 module Relax
+  # Response is intended to be a parent class for responses passed to
+  # Service#call.
+  #
+  # A response is in essence an object used to facilitate XML parsing. It
+  # stores an XML document, and provides access to it through methods like
+  # #element and #attribute.
   class Response
     attr_accessor :xml
 
+    # New takes in the XML from the response. For the initial response, this
+    # will be the root element, but child elements may also be passed into
+    # Response objects.
     def initialize(xml)
       @xml = Hpricot.XML(xml.to_s)
 
@@ -29,7 +38,10 @@ module Relax
               options[:collection].new(element)
             end
           else
-            case options[:type]
+            case type = options[:type]
+              when Response
+                value = type.new(node)
+
               when :float
                 value = float_value(node)
 
@@ -47,62 +59,89 @@ module Relax
       end
     end
 
+    # Returns the root of the XML document.
     def root
       @xml.root
     end
 
+    # Checks the name of the root node.
     def is?(name)
       root.name.gsub(/.*:(.*)/, '\1') == node_name(name)
     end
 
+    # Returns an element of the specified name.
     def element(name)
       root.at(root_path(name))
     end
+    alias :has? :element
 
+    # Returns an attribute on an element.
     def attribute(element, name)
       element[name]
     end
 
+    # Returns a set of elements matching name.
     def elements(name)
       root.search(root_path(name))
     end
 
+    # Gets the value of an element or attribute.
     def value(value)
       value.is_a?(Hpricot::Elem) ? value.inner_text : value.to_s
     end
 
+    # Gets a text value.
     def text_value(value)
       value(value)
     end
 
+    # Gets an integer value.
     def integer_value(value)
       value(value).to_i
     end
 
+    # Gets a float value.
     def float_value(value)
       value(value).to_f
     end
 
+    # Gets a date value.
     def date_value(value)
       Date.parse(value(value))
     end
 
-    alias :has? :element
-
     class << self
+      # Specifes a parameter that will be automatically parsed when the
+      # Response is instantiated.
+      #
+      # Options:
+      # - <tt>:attribute</tt>: An attribute name to use, or <tt>true</tt> to
+      #   use the <tt>:element</tt> value as the attribute name on the root.
+      # - <tt>:collection</tt>: A class used to instantiate each item when
+      #   selecting a collection of elements.
+      # - <tt>:element</tt>: The XML element name.
+      # - <tt>:object</tt>: A class used to instantiate an element.
+      # - <tt>:type</tt>: The type of the parameter. Should be one of
+      #   <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, or <tt>:date</tt>.
       def parameter(name, options = {})
         attr_accessor name
         @parameters ||= {}
         @parameters[name] = options
       end
+
+      def ===(response)
+        response.is_a?(Class) ? response.ancestors.include?(self) : super
+      end
     end
 
     private
 
+    # Converts a name to a node name.
     def node_name(name)
-      name.to_s.downcase
+      name.to_s
     end
 
+    # Gets the XPath expression representing the root node.
     def root_path(name)
       "/#{node_name(name)}"
     end

data/lib/relax/service.rb

@@ -0,0 +1,101 @@
+require 'openssl'
+require 'net/https'
+require 'uri'
+require 'date'
+require 'base64'
+require 'erb'
+
+module Relax
+  # Service is the starting point for any REST consumer written with Relax. It
+  # is responsible for setting up the endpoint for the service, and issuing the
+  # HTTP requests for each call made.
+  #
+  # == Extending Service
+  #
+  # When writing consumers, you should start by extending Service by inheriting
+  # from it and calling its constructor with the endpoint for the service.
+  #
+  # === Example
+  #
+  #   class Service < Relax::Service
+  #     ENDPOINT = 'http://example.com/services/rest/'
+  #
+  #     def initialize
+  #       super(ENDPOINT)
+  #     end
+  #   end
+  #
+  # == Calling a Service
+  #
+  # Each call made to the service goes through the #call method of Service,
+  # which takes in a Request object and a Response class. The Request object is
+  # used to generate the query string that will be passed to the endpoint. The
+  # Reponse class is instantiated with the body of the response from the HTTP
+  # request.
+  #
+  # === Example
+  #
+  # This example show how to create a barebones call. This module can be then
+  # included into your Service class.
+  #
+  #   module Search
+  #     class SearchRequest < Relax::Request
+  #     end
+  #
+  #     class SearchResponse < Relax::Response
+  #     end
+  #
+  #     def search(options = {})
+  #       call(SearchRequest.new(options), SearchResponse)
+  #     end
+  #   end
+  #
+  class Service
+    attr_reader :endpoint
+
+    # This constructor should be called from your Service with the endpoint URL
+    # for the REST service.
+    def initialize(endpoint)
+      @endpoint = URI::parse(endpoint)
+    end
+
+    protected
+
+    # Calls the service using a query built from the Request object passed in
+    # as its first parameter. Once the response comes back from the service,
+    # the body of the response is used to instantiate the response class, and
+    # this response object is returned.
+    def call(request, response_class)
+      uri = @endpoint.clone
+      uri.query = query(request).to_s
+      response = request(uri)
+      puts "Response:\n#{response.body}\n\n" if $DEBUG
+      response_class.new(response.body)
+    end
+
+    private
+
+    def default_query
+      Query.new
+    end
+
+    def query(request)
+      Query.new(default_query.merge(request.to_query))
+    end
+
+    def request(uri)
+      puts "Request:\n#{uri.to_s}\n\n" if $DEBUG
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      if uri.scheme == 'https'
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      http.start do |http|
+        request = Net::HTTP::Get.new("#{uri.path}?#{uri.query}")
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/relax/symbolic_hash.rb

@@ -1,4 +1,20 @@
 module Relax
+  # SymbolicHash provides an extension of Hash, but one that only supports keys
+  # that are symbols. This has been done in an effort to prevent the case where
+  # both a string key and a symbol key are set on the same hash, and espcially
+  # for dealing with this particular case when convert the hash to a string.
+  #
+  # === Example
+  #
+  #   hash = Relax::SymbolicHash.new
+  #   hash[:one] = 1
+  #   hash['one'] = 2
+  #   puts hash[:one] # => 2
+  #
+  # === Credits
+  #
+  # Some of the inspiration (and code) for this class comes from the
+  # HashWithIndifferentAccess that ships with Rails.
   class SymbolicHash < Hash
     def initialize(constructor = {})
       if constructor.is_a?(Hash)
@@ -21,8 +37,7 @@ module Relax
       other_hash.each_pair { |key, value| store(convert_key(key), convert_value(value)) }
       self
     end
-
-    alias_method :merge!, :update
+    alias :merge! :update
 
     def fetch(key, *extras)
       super(convert_key(key), *extras)
@@ -47,10 +62,9 @@ module Relax
     def key?(key)
       super(convert_key(key))
     end
-
-    alias_method :include?, :key?
-    alias_method :has_key?, :key?
-    alias_method :member?, :key?
+    alias :include? :key?
+    alias :has_key? :key?
+    alias :member? :key?
 
     protected
 

data/lib/relax.rb

@@ -1,7 +1,7 @@
 $:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
-require 'relax/api'
-require 'relax/symbolic_hash'
 require 'relax/query'
 require 'relax/request'
 require 'relax/response'
+require 'relax/service'
+require 'relax/symbolic_hash'

data/spec/response_spec.rb

@@ -15,6 +15,10 @@ XML = <<EOF
   </Tokens>
   <Status>Success</Status>
   <RequestId valid="true">44287</RequestId>
+  <Error>
+    <Code>1</Code>
+    <Message>Failed</Message>
+  </Error>
 </RESTResponse>
 EOF
 
@@ -24,10 +28,16 @@ class TestResponse < Relax::Response
     parameter :status
   end
 
+  class Error < Relax::Response
+    parameter :code, :type => :integer
+    parameter :message
+  end
+
   parameter :status
   parameter :request_id, :element => :requestid, :type => :integer
   parameter :valid_request, :element => :requestid, :attribute => :valid
   parameter :tokens, :collection => Token
+  parameter :error, :type => Error
 end
 
 describe 'a response' do
@@ -38,7 +48,7 @@ describe 'a response' do
   it 'should allow access to the root' do
     root = @response.root
     root.should be_an_instance_of(Hpricot::Elem)
-    root.name.should eql('restresponse')
+    root.name.should eql('RESTResponse')
   end
 
   it 'should be checkable by the name of its root' do
@@ -66,7 +76,7 @@ describe 'a response' do
     @response.has?(:Errors).should be_nil
   end
 
-  it 'should be able to define children of Request without modifying parent' do
+  it 'should be able to define children of Response without modifying parent' do
     Relax::Response.new(XML).respond_to?(:status).should be_false
     TestResponse.new(XML).respond_to?(:status).should be_true
   end
@@ -78,5 +88,11 @@ describe 'a response' do
     response.valid_request.should eql('true')
     response.tokens.length.should eql(2)
     response.tokens.first.status.should eql('Active')
+    response.error.code.should eql(1)
+    response.error.message.should eql('Failed')
+  end
+
+  it 'should be relationally equivalent to its children' do
+    (Relax::Response === TestResponse).should be_true
   end
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: relax
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2007-09-24 00:00:00 -04:00
+  version: 0.0.2
+date: 2007-10-10 00:00:00 -04:00
 summary: A simple library for creating REST consumers.
 require_paths: 
 - lib
@@ -32,8 +32,8 @@ files:
 - lib/relax.rb
 - lib/relax
 - lib/relax/response.rb
-- lib/relax/api.rb
 - lib/relax/request.rb
+- lib/relax/service.rb
 - lib/relax/query.rb
 - lib/relax/symbolic_hash.rb
 - README
@@ -62,5 +62,5 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: "0.5"
+        version: "0.6"
     version: 

data/lib/relax/api.rb

@@ -1,49 +0,0 @@
-require 'openssl'
-require 'net/https'
-require 'uri'
-require 'date'
-require 'base64'
-require 'erb'
-
-module Relax
-  class API
-    attr_reader :endpoint
-
-    def initialize(endpoint)
-      @endpoint = URI::parse(endpoint)
-    end
-
-    private
-
-    def default_query
-      Query.new
-    end
-
-    def query(request)
-      Query.new(default_query.merge(request.to_query))
-    end
-
-    def call(request, response_class)
-      uri = @endpoint.clone
-      uri.query = query(request).to_s
-      response = request(uri)
-      puts "Response:\n#{response.body}\n\n" if $DEBUG
-      response_class.new(response.body)
-    end
-
-    def request(uri)
-      puts "Request:\n#{uri.to_s}\n\n" if $DEBUG
-      http = Net::HTTP.new(uri.host, uri.port)
-
-      if uri.scheme == 'https'
-        http.use_ssl = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      end
-
-      http.start do |http|
-        request = Net::HTTP::Get.new("#{uri.path}?#{uri.query}")
-        http.request(request)
-      end
-    end
-  end
-end