rc-rest 1.0.0

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2006 Eric Hodel, The Robot Co-op.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the names of the authors nor the names of their contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Manifest.txt

@@ -0,0 +1,7 @@
+LICENSE
+Manifest.txt
+README
+Rakefile
+lib/rc_rest.rb
+lib/rc_rest/uri_stub.rb
+test/test_rc_rest.rb

data/README

@@ -0,0 +1,27 @@
+= rc-rest
+
+Rubyforge Project:
+
+http://rubyforge.org/projects/rctools/
+
+Documentation:
+
+http://dev.robotcoop.com/Libraries/rc-rest/
+
+== About
+
+This is an abstract class for REST web service APIs.  By itself it isn't at all
+useful.
+
+== Installing rc-rest
+
+Just install the gem:
+
+  $ sudo gem install rc-rest
+
+== Using rc-rest
+
+rc-rest is used by gems such as yahoo-search, google-geocode and geocoder-us.
+If you'd like to write bindings a web service using rc-rest see RCRest, its
+tests or the above-mentioned gems for examples.
+

data/Rakefile

@@ -0,0 +1,66 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+$VERBOSE = nil
+
+spec = Gem::Specification.new do |s|
+  s.name = 'rc-rest'
+  s.version = '1.0.0'
+  s.summary = 'Robot Co-op REST web services base class'
+  s.description = 'This library makes it easy to implement REST-like web services APIs.'
+  s.author = 'Eric Hodel'
+  s.email = 'eric@robotcoop.com'
+
+  s.has_rdoc = true
+  s.files = File.read('Manifest.txt').split($/)
+  s.require_path = 'lib'
+end
+
+desc 'Run tests'
+task :default => [ :test ]
+
+Rake::TestTask.new('test') do |t|
+  t.libs << 'test'
+  t.pattern = 'test/test_*.rb'
+  t.verbose = true
+end
+
+desc 'Update Manifest.txt'
+task :update_manifest do
+  sh "find . -type f | sed -e 's%./%%' | egrep -v 'svn|swp|~' | egrep -v '^(doc|pkg)/' | sort > Manifest.txt"
+end
+
+desc 'Generate RDoc'
+Rake::RDocTask.new :rdoc do |rd|
+  rd.rdoc_dir = 'doc'
+  rd.rdoc_files.add 'lib', 'README', 'LICENSE'
+  rd.main = 'README'
+  rd.options << '-d' if `which dot` =~ /\/dot/
+  rd.options << '-t Robot Co-op REST Web Services'
+end
+
+desc 'Generate RDoc for dev.robotcoop.com'
+Rake::RDocTask.new :dev_rdoc do |rd|
+  rd.rdoc_dir = '../../../www/trunk/dev/html/Libraries/rc-rest'
+  rd.rdoc_files.add 'lib', 'README', 'LICENSE'
+  rd.main = 'README'
+  rd.options << '-d' if `which dot` =~ /\/dot/
+  rd.options << '-t Robot Co-op REST Web Services'
+end
+
+desc 'Build Gem'
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = true
+end
+
+desc 'Clean up'
+task :clean => [ :clobber_rdoc, :clobber_package ]
+
+desc 'Clean up'
+task :clobber => [ :clean ]
+
+# vim: syntax=Ruby
+

data/lib/rc_rest.rb

@@ -0,0 +1,115 @@
+require 'open-uri'
+require 'rexml/document'
+
+##
+# Abstract class for implementing REST APIs.
+#
+# === Example
+#
+# The following methods must be implemented in sublcasses:
+#
+# +initialize+:: Sets @url to the service enpoint.
+# +check_error+:: Checks for errors in the server response.
+# +parse_response+:: Extracts information from the server response.
+#
+# If you have extra URL paramaters (application id, output type) or need to
+# perform URL customization, override +make_url+.
+#
+#   class FakeService < RCRest
+#   
+#     class Error < RCRest::Error; end
+#   
+#     def initialize(appid)
+#       @appid = appid
+#       @url = URI.parse 'http://example.com/test'
+#     end
+#   
+#     def check_error(xml)
+#       raise Error, xml.elements['error'].text if xml.elements['error']
+#     end
+#   
+#     def make_url(params)
+#       params[:appid] = @appid
+#       super params
+#     end
+#   
+#     def parse_response(xml)
+#       return xml
+#     end
+#   
+#     def test(query)
+#       get :q => query
+#     end
+#   
+#   end
+
+class RCRest
+
+  ##
+  # Error class.
+
+  class Error < RuntimeError; end
+
+  ##
+  # Web services initializer.
+  #
+  # Concrete web services implementations must set the +url+ instance
+  # variable which must be a URI.
+
+  def initialize
+    raise NotImplementedError
+  end
+
+  ##
+  # Must extract and raise an error from +xml+, an REXML::Document, if any.
+  # Must returns if no error could be found.
+
+  def check_error(xml)
+    raise NotImplementedError
+  end
+
+  ##
+  # Performs a GET request with +params+.  Calls the parse_response method on
+  # the concrete class with an REXML::Document instance and returns its
+  # result.
+
+  def get(params = {})
+    url = make_url params
+
+    url.open do |xml|
+      res = REXML::Document.new xml.read
+
+      check_error res
+
+      return parse_response(res)
+    end
+  rescue OpenURI::HTTPError => e
+    xml = REXML::Document.new e.io.read
+    check_error xml
+    raise
+  end
+
+  ##
+  # Creates a URI from the Hash +params+.  Override this then call super if
+  # you need to add extra params like an application id or output type.
+
+  def make_url(params)
+    escaped_params = params.sort_by { |k,v| k.to_s }.map do |k,v|
+      "#{URI.escape k.to_s}=#{URI.escape v.to_s}"
+    end
+
+    url = @url.dup
+    url.query = escaped_params.join '&'
+    return url
+  end
+
+  ##
+  # Must parse results from +xml+, an REXML::Document, into something sensible
+  # for the API.
+
+  def parse_response(xml)
+    raise NotImplementedError
+  end
+
+end
+

data/lib/rc_rest/uri_stub.rb

@@ -0,0 +1,51 @@
+require 'open-uri'
+
+module URI # :nodoc:
+end
+
+##
+# This stub overrides OpenURI's open method to allow programs that use OpenURI
+# to be easily tested.
+#
+# == Usage
+#
+#   require 'rc_rest/uri_stub'
+#   
+#   class TestMyClass < Test::Unit::TestCase
+#     
+#     def setup
+#       URI::HTTP.responses = []
+#       URI::HTTP.uris = []
+#       
+#       @obj = MyClass.new
+#     end
+#     
+#     def test_my_method
+#       URI::HTTP.responses << 'some text open would ordinarily return'
+#       
+#       result = @obj.my_method
+#       
+#       assert_equal :something_meaninfgul, result
+#       
+#       assert_equal true, URI::HTTP.responses.empty?
+#       assert_equal 1, URI::HTTP.uris.length
+#       assert_equal 'http://example.com/path', URI::HTTP.uris.first
+#     end
+#     
+#  end
+
+class URI::HTTP # :nodoc:
+
+  class << self
+    attr_accessor :responses, :uris
+  end
+
+  alias original_open open
+
+  def open
+    self.class.uris << self.to_s
+    yield StringIO.new(self.class.responses.shift)
+  end
+
+end
+

data/test/test_rc_rest.rb

@@ -0,0 +1,97 @@
+require 'test/unit'
+require 'rc_rest/uri_stub'
+require 'rc_rest'
+
+class FakeService < RCRest
+
+  class Error < RCRest::Error; end
+
+  def initialize
+    @url = URI.parse 'http://example.com/test'
+  end
+
+  def check_error(xml)
+    raise Error, xml.elements['error'].text if xml.elements['error']
+  end
+
+  def test
+    get
+  end
+
+  def parse_response(xml)
+    return xml
+  end
+
+end
+
+class TestFakeService < Test::Unit::TestCase
+
+  def setup
+    URI::HTTP.responses = []
+    URI::HTTP.uris = []
+
+    @fs = FakeService.new
+  end
+
+  def test_check_error
+    xml = REXML::Document.new '<error>you broked it</error>'
+    @fs.check_error xml
+
+  rescue FakeService::Error => e
+    assert_equal 'you broked it', e.message
+
+  else
+    flunk 'expected an error'
+  end
+
+  def test_get
+    xml = '<result>stuff</result>'
+    URI::HTTP.responses << xml
+
+    result = @fs.test
+
+    assert_equal xml, result.to_s
+  end
+
+  def test_get_error
+    def @fs.make_url(*args) # HACK extend uri_stub with error raising ability
+      u = Object.new
+      def u.open
+        xml = '<error>you did the bad thing</error>'
+        raise OpenURI::HTTPError.new('400 Bad Request', StringIO.new(xml))
+      end
+      return u
+    end
+
+    assert_raise FakeService::Error do @fs.test end
+  end
+
+end
+
+class TestRCRest < Test::Unit::TestCase
+
+  def test_initialize
+    assert_raise NotImplementedError do RCRest.new end
+  end
+
+  def test_check_error
+    r = RCRest.allocate
+    assert_raise NotImplementedError do r.check_error nil end
+  end
+
+  def test_make_url
+    r = RCRest.allocate
+    r.instance_variable_set :@url, URI.parse('http://example.com/')
+
+    url = r.make_url :a => 'b c', :x => 'y z'
+
+    assert_equal 'http://example.com/?a=b%20c&x=y%20z', url.to_s
+  end
+
+  def test_parse_response
+    r = RCRest.allocate
+    assert_raise NotImplementedError do r.parse_response nil end
+  end
+
+end
+

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.99
+specification_version: 1
+name: rc-rest
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-06-15 00:00:00 -07:00
+summary: Robot Co-op REST web services base class
+require_paths: 
+- lib
+email: eric@robotcoop.com
+homepage: 
+rubyforge_project: 
+description: This library makes it easy to implement REST-like web services APIs.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Eric Hodel
+files: 
+- LICENSE
+- Manifest.txt
+- README
+- Rakefile
+- lib/rc_rest.rb
+- lib/rc_rest/uri_stub.rb
+- test/test_rc_rest.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+