relax 0.0.7 → 0.1.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2008 Tyler Hunt
+Copyright (c) 2007-2009 Tyler Hunt
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README

@@ -1,171 +1,194 @@
 = Relax
 
-Relax is a simple library that provides a foundation for writing REST consumer
-APIs, including the logic to handle the HTTP requests, build URLs with query
-parameters, and parse XML responses.
-
-It provides a basic set of functionality common to most REST consumers:
-
-- building HTTP queries (Relax::Request)
-- issuing HTTP requests (Relax::Service)
-- parsing XML responses (Relax::Response)
+Relax is a library that provides a foundation for writing REST consumer APIs,
+including the logic to handle the HTTP requests, build URLs with query
+parameters, and parse responses.
 
 
 == 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.
+This short tutorial will walk you through the basic steps of creating a simple Flickr API consumer that supports a single call to search for photos by tags.
+
 
-=== Step 1
+=== First Things First
 
-In the first step we're going to simply include Relax, and define the basis for
-our Service class.
+The first step we'll take is to load the Relax gem.
 
   require 'rubygems'
+
+  gem 'relax', '~> 0.1.0'
   require 'relax'
 
-  module Flickr
-    class Service < Relax::Service
-      ENDPOINT = 'http://api.flickr.com/services/rest/'
+Then we'll define our service class.
 
-      def initialize
-        super(ENDPOINT)
-      end
-    end
+  class Flickr < Relax::Service
   end
 
 
-=== Step 2
+=== Adding an Endpoint
 
-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.
+An endpoint is the base URL for the service we'll be consuming. All of our
+actions will be nested inside of an endpoint and build on top of it to
+forumlate the final request URL.
 
-  module Flickr
-    class Request < Relax::Request
-      parameter :method
+  class Flickr < Relax::Service
+    endpoint 'http://api.flickr.com/services/rest/' do
     end
+  end
 
-    class Response < Relax::Response
-      def successful?
-        root[:stat] == 'ok'
-      end
+
+=== Adding Default Parameters
+
+Since Flickr requires us to always pass an API key parameter let's make that a
+ required default parameter in our service class.
+
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
     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
+    endpoint 'http://api.flickr.com/services/rest/' do
     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.
 
+=== Adding an Action
 
-=== Step 3
+So we have our service now, but we need to define an action before we can
+actually fetch any data from it.
 
-Next, we're going to need a basic Photo class to represent photos that Flickr
-returns to us.
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
+    end
 
-  module Flickr
-    class Photo < Response
-      parameter :id, :attribute => true, :type => :integer
-      parameter :title, :attribute => true
+    endpoint 'http://api.flickr.com/services/rest/' do
+      action :search do
+        parameter :method, :default => 'flickr.photos.search'
+        parameter :per_page, :default => 5
+        parameter :tags
+      end
     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.
+We're defining an action here called <tt>:search</tt> that will create an
+instance method on our service with the same name. There are three parameters,
+<tt>:method</tt>, <tt>:per_page</tt>, and <tt>:tags</tt>, with <tt>:method</tt>
+and <tt>:per_page</tt> receiving default values.
 
+There are lots of other parameters for the <tt>flickr.photos.search</tt> method
+that we could define, but we'll just stick with these for simplicities sake.
 
-=== 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.
+=== A Small Refactoring
 
-There are three main pieces to every service call module:
+When adding more methods it will quickly become obvious that we have another
+common parameter in <tt>:method</tt>. We can refactor our service class
+slightly to make this a default parameter for all of the actions on our
+endpoint.
 
-1. a Relax::Request object
-2. a Relax::Response object
-3. a call method that calls Relax::Service#call
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
+    end
 
-Here's what the PhotoSearch module looks like:
+    endpoint 'http://api.flickr.com/services/rest/' do
+      defaults do
+        parameter :method, :required => true
+      end
 
-  module Flickr
-    module PhotoSearch
-      class PhotoSearchRequest < Flickr::Request
-        parameter :per_page
+      action :search do
+        set :method, 'flickr.photos.search'
+        parameter :per_page, :default => 5
         parameter :tags
-
-        def initialize(options = {})
-          super
-          @method = 'flickr.photos.search'
-        end
       end
+    end
+  end
 
-      class PhotoSearchResponse < Flickr::Response
-        parameter :photos, :element => 'photos/photo', :collection => Photo
-      end
+The <tt>set</tt> method allows us to define a default value for a default
+parameter so we don't have to redefine common parameters inside every action.
 
-      def search(options = {})
-        call(PhotoSearchRequest.new(options), PhotoSearchResponse)
-      end
 
-      def find_by_tag(tags, options = {})
-        search(options.merge(:tags => tags))
-      end
+=== Defining a Parser
+
+Before we can actually perform a request we need to let the service know how to
+handle the response. This is done by defining a parser.
+
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
     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 now needs to be included into our Flickr::Service class,
-and then we'll be able to use it by calling either of the call methods.
+    endpoint 'http://api.flickr.com/services/rest/' do
+      defaults do
+        parameter :method, :required => true
+      end
 
-  module Flickr
-    class Service < Relax::Service
-      include Flickr::PhotoSearch
+      action :search do
+        set :method, 'flickr.photos.search'
+        parameter :per_page, :default => 5
+        parameter :tags
 
-      ENDPOINT = 'http://api.flickr.com/services/rest/'
-      
-      def initialize(api_key)
-        super(ENDPOINT)
-        Request[:api_key] = api_key
+        parser :rsp do
+          attribute :stat, :as => :status
+
+          element :photos do
+            attribute :page
+            attribute :pages
+            attribute :perpage, :as => :per_page
+            attribute :total
+
+            elements :photo do
+              attribute :id
+              attribute :owner
+              attribute :secret
+              attribute :server
+              attribute :farm
+              attribute :title
+              attribute :ispublic, :as => :is_public
+              attribute :isfriend, :as => :is_friend
+              attribute :isfamily, :as => :is_family
+            end
+          end
+        end
       end
     end
   end
 
-Now we're ready to make a call against the API:
+dhe parsing is performed by the Relief gem, so you can find out more about the
+syntax in its own documentation.
 
-  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
+=== Making a Call
+
+Now, we're able to create a new instance of our service with the API key set.
+
+  flickr = Flickr.new(:api_key => FLICKR_API_KEY)
+
+We can now use this object to search for photos by tag.
+
+  flickr.search(:tags => 'cucumbers,lemons')
+
+This will return a Ruby response hash.
+
+  {
+    :status => "ok",
+    :photos => {
+      :page => "1",
+      :pages => "3947",
+      :per_page => "5",
+      :total => "19733",
+      :photo => [
+        { :is_public => "1", :secret => "3c196485d2", :server => "3182", :is_friend => "0", :farm => "4", :title => "lemons", :is_family => "0", :id => "3509955709", :owner => "37013676@N06" },
+        { :is_public => "1", :secret => "44f1306a63", :server => "3326", :is_friend => "0", :farm => "4", :title => "Peeto", :is_family => "0", :id => "3509461859", :owner => "13217824@N04" },
+        { :is_public => "1", :secret => "dce53bce7f", :server => "3364", :is_friend => "0", :farm => "4", :title => "Peeto Above", :is_family => "0", :id => "3509459585", :owner => "13217824@N04" },
+        { :is_public => "1", :secret => "12f9ba167c", :server => "3632", :is_friend => "0", :farm => "4", :title => "Lemonaid", :is_family => "0", :id => "3509415752", :owner => "35666391@N03" },
+        { :is_public => "1", :secret => "8caac1ff46", :server => "3320", :is_friend => "0", :farm => "4", :title => "Gardening 365 (Day 8)", :is_family => "0", :id => "3509251322", :owner => "21778017@N06" }
+      ]
+    }
+  }
 
-This will output the IDs and titles for the first 10 photos on Flickr that have
-the tag "relax."
 
+== Copyright
 
-Copyright (c) 2007-2008 Tyler Hunt, released under the MIT license
+Copyright (c) 2007-2009 Tyler Hunt. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+    gem.name = "relax"
+    gem.summary = %Q{A flexible library for creating web service consumers.}
+    gem.email = "tyler@tylerhunt.com"
+    gem.homepage = "http://github.com/tylerhunt/relax"
+    gem.authors = ["Tyler Hunt"]
+    gem.rubyforge_project = 'relax'
+
+    gem.add_dependency('rest-client', '~> 0.9.2')
+    gem.add_dependency('nokogiri', '~> 1.2.3')
+    gem.add_dependency('relief', '~> 0.0.3')
+
+    gem.add_development_dependency('jeweler', '~> 0.11.0')
+    gem.add_development_dependency('rspec', '~> 1.2.2')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+task :default => :spec
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "relief #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('LICENSE*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 0

data/lib/relax/action.rb

@@ -0,0 +1,39 @@
+module Relax
+  class Action
+    include Contextable
+
+    attr_reader :name
+
+    def initialize(endpoint, name, options, &block)
+      @endpoint = endpoint
+      @name = name
+      @options = options
+
+      extend_context(endpoint)
+      context.evaluate(&block) if block_given?
+    end
+
+    def execute(values, credentials, *args)
+      args.unshift(values) if values
+      instance = Instance.new(*args)
+      response = performer(instance, credentials).perform
+      context.parse(response)
+    end
+
+    def method
+      @options[:method] || :get
+    end
+    private :method
+
+    def url
+      [@endpoint.url, @options[:url]].join
+    end
+    private :url
+
+    def performer(instance, credentials)
+      values = instance.values(context)
+      Performer.new(method, url, values, credentials)
+    end
+    private :performer
+  end
+end

data/lib/relax/context.rb

@@ -0,0 +1,40 @@
+module Relax
+  class Context
+    attr_reader :parameters
+
+    def initialize(parameters=[]) # :nodoc:
+      @parameters = parameters
+    end
+
+    def evaluate(&block) # :nodoc:
+      instance_eval(&block)
+    end
+
+    def parameter(name, options={})
+      unless @parameters.find { |parameter| parameter.name == name }
+        @parameters << Parameter.new(name, options)
+      else
+        raise ArgumentError.new("Duplicate parameter '#{name}'.")
+      end
+    end
+
+    def set(name, value)
+      if parameter = @parameters.find { |parameter| parameter.name == name }
+        parameter.value = value
+      end
+    end
+
+    def parser(root, options={}, &block) # :nodoc:
+      @parser ||= Relief::Parser.new(root, options, &block)
+    end
+
+    def parse(response) # :nodoc:
+      @parser.parse(response)
+    end
+
+    def clone # :nodoc:
+      cloned_parameters = @parameters.collect { |parameter| parameter.clone }
+      self.class.new(cloned_parameters)
+    end
+  end
+end

data/lib/relax/contextable.rb

@@ -0,0 +1,15 @@
+module Relax
+  module Contextable # :nodoc:
+    def context
+      @context ||= Context.new
+    end
+
+    def extend_context(base)
+      @context = base.context.clone
+    end
+
+    def defaults(&block)
+      context.evaluate(&block)
+    end
+  end
+end

data/lib/relax/endpoint.rb

@@ -0,0 +1,21 @@
+module Relax
+  class Endpoint
+    include Contextable
+
+    attr_reader :url
+
+    def initialize(service, url, options, &block)
+      @service = service
+      @url = url
+      @options = options
+
+      extend_context(service)
+      instance_eval(&block)
+    end
+
+    def action(name, options={}, &block)
+      action = Action.new(self, name, options, &block)
+      @service.register_action(action)
+    end
+  end
+end

data/lib/relax/instance.rb

@@ -0,0 +1,23 @@
+module Relax
+  class Instance # :nodoc:
+    def initialize(*args)
+      @values = args.inject({}) do |values, arg|
+        arg.is_a?(Hash) ? values.merge(arg) : values
+      end
+    end
+
+    def values(context)
+      context.parameters.inject({}) do |values, parameter|
+        name = parameter.name
+
+        if value = @values[parameter.name] || parameter.value
+          values[parameter.name] = value
+        elsif parameter.required?
+          raise ArgumentError.new("Missing value for '#{parameter.name}'.")
+        end
+
+        values
+      end
+    end
+  end
+end

data/lib/relax/parameter.rb

@@ -0,0 +1,19 @@
+module Relax
+  class Parameter
+    attr_reader :name, :options
+    attr_writer :value
+
+    def initialize(name, options={})
+      @name = name
+      @options = options
+    end
+
+    def value
+      @value || @options[:default]
+    end
+
+    def required?
+      @options[:required]
+    end
+  end
+end

data/lib/relax/performer.rb

@@ -0,0 +1,32 @@
+module Relax
+  class Performer
+    def initialize(method, url, values, credentials)
+      @method = method
+      @url = url
+      @values = values
+      @credentials = credentials
+    end
+
+    def perform
+      case @method
+        when :delete, :get, :head then RestClient.send(@method, url)
+        when :post, :put then RestClient.send(@method, url, query)
+      end
+    end
+
+    def url
+      uri = URI.parse(@url)
+      uri.query = query unless query.nil? || query.empty?
+      uri.userinfo = @credentials.join(':') if @credentials
+      uri.to_s
+    end
+    private :url
+
+    def query
+      @values.collect do |name, value|
+        "#{name}=#{value}" if value
+      end.compact.join('&')
+    end
+    private :query
+  end
+end