remote_api 0.1.2 → 0.2.0

data/Manifest.txt

@@ -12,7 +12,9 @@ lib/remote_api/xml_response.rb
 
 lib/remote_api/version.rb
 
-test/test_helper.rb
-test/base_test.rb
-test/xml_test.rb
-test/xml_response_test.rb
+test/spec_test.rb
+
+spec/base_spec.rb
+spec/spec_helper.rb
+spec/xml_response_spec.rb
+spec/xml_spec.rb

data/README.txt

@@ -1,41 +1,112 @@
-Simple Readme for now.
+= Remote API
 
 Rubyforge Project: http://rubyforge.org/projects/remote-api/
 
-=== Installation
+Installation: <tt>gem install remote_api</tt>
 
-  gem install remote_api
+== Overview
 
-=== Example
++RemoteAPI+ is an abstraction from API classes.  I noticed that there was very overlapping 
+functionality in the various API wrappers I had going.  This gem will make it much easier to
+write an API wrapper by taking care of the common stuff.  All you have to do is write the
+parts that are specific to the API you are talking to.
+
+=== Usage and Checklist
+
+To use this gem you should follow this simple checklist of things that you must implement on
+your own.
+
+1. Create a class that descends from RemoteAPI: <tt>class Foo < RemoteAPI; end</tt>
+2. Define the url to access with the url dsl_accessor <tt>url 'some url here'</tt>
+3. Add a +request+ method to your class.  This should return the body of your request.
+4. Add a +assert_response+ method.  This method should raise exceptions if the contents
+   of <tt>@response</tt> describe a fatal error.
+5. Add a +process+ method.  This parses the API response.  It should pull the relevant
+   data out of the <tt>@response</tt> object and put it in instance variables.
+6. Create <tt>attr_reader</tt>s for the instance variables from the +process+ method that
+   you want to expose as methods.
+
+=== Basic Walkthrough
+
+I'm going to explain just what happens under the hood of a class that inherits from RemoteAPI.
+
+So lets say that I am writing an API to ship a package.  It requires address and weight, each 
+on their own line in a YAML like format.  On success, it returns the tracking number of the 
+package.  On failure it just says "There was an error!".
+
+Here is an API class that can handle that:
 
-This is an example of how to access a little API that allows you to change the title of an object.
-The API would return the title, but in Title Case, and we want to capture that.
-  
   require 'remote_api'
   
-  class MyAPI < RemoteAPI
-    
-    attr_reader :title
-    
-    url 'http://test.com/posts/change_title'
+  class Shipment < RemoteAPI
+    attr_reader :tracking_number
+    url 'http://test.com/shipments'
     
     def request
-      "title=#{@title}&post_id={@post_id}"
+      <<-EOF
+        address: #{@address}
+        weight: #{@weight}
+      EOF
     end
     
     def assert_success
-      if @response =~ /&?error=(.+?)&?/
-        raise ResponseFailure, $1
-      end
+      raise ResponseFailure if @response =~ /error/
     end
     
     def process
-      @title = @response.match(/&?title=(.+?)&?/)[1]
+      @tracking_number = @response
     end
     
   end
+
+All the magic happens on instantiation.  The request is built and sent, and the response is 
+processed.  It all starts with:
+
+  Shipment.new(:address => '123 Fake St', :weight => 12)
+
+==== Instantiation
+
+The hash passed to +new+ is converted to instance variables.  In this case the Shipment instance
+now has <tt>@address</tt> and <tt>@weight</tt> instance variables in it.
+
+==== Building the request
+
+The next step is the +request+ method is called.  This should return a string, something that can 
+be converted to a sttring.  This string will be sent out as the request body to the remote server.
+
+==== Sending the request
+
+Now that we have built the request, the connection is made to the remote server at the url defined
+by the dsl_accessor +url+.  The request is sent with the result of the +request+ method as the body.
+What the server returns is stored in the <tt>@response</tt> variable.  This all happens automatically.
+
+==== Assertion of Success
+
+Most API's have some sort of error reporting.  The <tt>assert_success</tt> method is for raising 
+exceptions if the API reports any errors.  The ResponseFailure exception is built into RemoteAPI.
+Parse the response to see if it reports errors.
+
+==== Processing the response
+
+You must deinfe a +process+ method.  This method will parse the response and stuff any needed data into
+instance varibales.  In this case, we are simply getting the entire response since that will be the 
+only tracking number that we are expecting.
+
+==== Using the result
+
+Define a <tt>attr_reader</tt> for each instance variable from the +process+ you want exposed.  Then use 
+your new object as you would any other object
+
+  pkg = Shipment.new(:address => '123 Fake St', :weight => 12)
+  puts "Sucess! Your tracking number is #{pkg.tracking_number}"
   
-  result = MyAPI.new(:post_id => 123, :title => 'hello world')
-  # API call happens here
+==== Using the result with Exception handling
+
+You probably don't want your whole app to crash if there is an API error.  This is why ruby has exception 
+handling
   
-  result.title #=> 'Hello World'
+  begin
+    pkg = Shipment.new(:address => '123 Fake St', :weight => 'foo')
+  rescue RemoteAPI::ResponseFailure
+    puts "Unable to ship that package.  The API really didn't like it."
+  end

data/Rakefile

@@ -46,4 +46,21 @@ hoe = Hoe.new(GEM_NAME, VERS) do |p|
   #p.changes        - A description of the release's latest changes.
   p.extra_deps = [['activesupport'], ['dsl_accessor']]
   #p.spec_extras    - A hash of extra values to set in the gemspec.
+end
+
+require 'spec/rake/spectask'
+desc "Run all specifications"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+end
+
+desc "Run all specification with spec output"
+Spec::Rake::SpecTask.new('spec_print') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ["-f", "s"]
+end
+
+desc "Tell you to run specs instead of tests"
+task :test do
+  puts "This gem has specs, not tests.  Run 'rake spec' or 'rake spec_print' instead"
 end

data/lib/remote_api/base.rb

@@ -1,42 +1,71 @@
 class RemoteAPI
   class ResponseFailure < RuntimeError; end
   
-  dsl_accessor :debug
+  dsl_accessor :debug
   dsl_accessor :log_file
   dsl_accessor :url
   dsl_accessor :content_type
-  
-  class ResponseFailure < RuntimeError; end
   
-  # Eeverything happens on instantiation.  Pass in a hash, and each key in the hash will 
-  # become an instance variable for use in the rest of the instance methods.
+  class ResponseFailure < RuntimeError; end
+  
+  # Prepare a new API object.  This will not make the actual remote 
+  # call until the +call+ method is used.  To execute the API call
+  # immediately, use the +call+ class method.
+  #
+  # Any options you pass in as a hash will be created as instance 
+  # variables.  So the below example will have an instance variable
+  # <tt>@foo</tt> in the generated API object.
+  # 
+  #   api = MyApi.new(:foo => 'bar')
+  #   api.call
+  #   api.some_result #=> "You said bar!"
   # 
-  # Then we send the request, assert that is the response is successful, and process the 
-  # response.
   def initialize(params = {})
     params.each do |k, v|
       instance_variable_set "@#{k}", v
     end
-    
-    send_request
-    assert_success
-    process
+  end
+  
+  # Instatiate and call the API in one step.
+  #
+  #   api = MyApi.call(:foo => 'bar')
+  #   api.some_result #=> "You said bar!"
+  #
+  def self.call(params = {})
+    returning new(params) do |api|
+      api.call
+    end
+  end
+  
+  # Execute an instance of an API object that has not been sent to the
+  # remote server yet.
+  # 
+  #   api = MyApi.new(:foo => 'bar')
+  #   api.call
+  #   api.some_result #=> "You said bar!"
+  #
+  def call
+    returning self do
+      send_request
+      assert_success
+      process
+    end
   end
   
   private
     
-    # Send the request to the UPS servers
+    # Send the request to the remote servers
     def send_request(request_body = nil)
       request_body ||= request
       debug_request(request_body)
       
       # Setup HTTP objects
-      url               = URI.parse(server_url)
-      http              = Net::HTTP.new(url.host, url.port)
+      url   = URI.parse(server_url)
+      http  = Net::HTTP.new(url.host, url.port)
       
       if url.is_a?(URI::HTTPS)
-	      http.verify_mode  = OpenSSL::SSL::VERIFY_NONE
-	      http.use_ssl      = true
+        http.verify_mode  = OpenSSL::SSL::VERIFY_NONE
+        http.use_ssl      = true
       end
       
       # Setup request options
@@ -49,28 +78,30 @@ class RemoteAPI
       
       # Convert response to proper format
       @response = prepare_response(response)
-      
-      # Code hook to raise execption if error conditions are met
+      
+      # Code hook to raise execption if error conditions are met
       assert_success
     end
     
-    def assert_success
-      true
-    end
+    # override this method and raises exception on failure
+    def assert_success; end
     
+    # override this method to parse your response
     def process
-      raise 'You must define a "process" method!  This should should parse the @response and' + 
-            'extract relevant data.'
-    end
-    
-    def request
-      raise 'You must define a "request" method!  This should create the body of your API request'
+      raise 'You must define a "process" method!  This should should parse the @response and extract relevant data.'
+    end
+    
+    # override this method to define your request body
+    def request
+      raise 'You must define a "request" method!  This should create the body of your API request'
     end
     
+    # Convert response to proper format
     def prepare_response(response)
       response.body
     end
     
+    # Get the full path to the remote server
     def server_url
       url = self.class.url
       
@@ -78,7 +109,11 @@ class RemoteAPI
       when 'String'
         url
       when 'Hash'
-        url.symbolize_keys[ENV['RAILS_ENV'].to_sym]
+        if env = ENV['RAILS_ENV']
+          url.symbolize_keys[ENV['RAILS_ENV'].to_sym]
+        else
+          raise 'Cannot use a hash for server url outside of a rails environment'
+        end
       when 'Proc'
         url.call
       else
@@ -86,16 +121,17 @@ class RemoteAPI
       end
     end
     
+    # Convert reponse to proper format
     def format_response(response)
       response
     end
-    
-    def log(data)
-      data = "\n\n\n\n\n*** #{Time.now}\n\n" + data
-      if file = self.class.log_file
-        File.open(file, 'a') { |f| f.write data }
-      end
-    end
+    
+    def log(data)
+      data = "\n\n\n\n\n*** #{Time.now}\n\n" + data
+      if file = self.class.log_file
+        File.open(file, 'a') { |f| f.write data }
+      end
+    end
     
     def debug_request(request_body)
       return unless self.class.debug || self.class.log_file
@@ -106,8 +142,8 @@ class RemoteAPI
 -----------
 
 #{request_body}
-DEBUG
-      puts text if self.class.debug
+DEBUG
+      puts text if self.class.debug
       log(text) if self.class.log_file
     end
     
@@ -125,9 +161,9 @@ DEBUG
 
 #{text}
 
-DEBUG
-
-     puts text if self.class.debug
+DEBUG
+
+     puts text if self.class.debug
      log(text) if self.class.log_file
     end
 end

data/lib/remote_api/version.rb

@@ -1,8 +1,8 @@
 class RemoteAPI #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 1
-    TINY  = 2
+    MINOR = 2
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/remote_api.rb

@@ -8,6 +8,6 @@ require 'active_support'
 require 'dsl_accessor'
 
 # remote_api
-require 'remote_api/base'
-require 'remote_api/xml'
-require 'remote_api/xml_response'
+%w( base xml xml_response ).each do |file|
+  require File.dirname(__FILE__) + '/remote_api/' + file
+end

data/spec/base_spec.rb

@@ -0,0 +1,65 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+FakeWeb.register_uri(
+  'http://test.com/base', 
+  :string => '<server_response>The server recieved your message</server_response>'
+)
+FakeWeb.register_uri(
+  'http://test.com/base/error', 
+  :string => '<server_response>An error occurred!</server_response>'
+)
+
+context "A Generic API" do
+  
+  setup do
+    BaseApi.url = 'http://test.com/base'
+  end
+  
+  specify "'initialize'_should_set_hash_keys_as_instance_variables" do
+    api = BaseApi.new(:foo => 'bar', :baz => 'taz', :message => 'Hello')
+    
+    api.instance_eval { @foo }.should_be      == 'bar'
+    api.instance_eval { @baz }.should_be      == 'taz'
+    api.instance_eval { @message }.should_be  == 'Hello'
+  end
+  
+  specify "instance method 'call' should perform API call" do
+    api = BaseApi.new(:message => 'Hello World!')
+    api.return_message.should_be_nil
+    
+    api.call
+    api.return_message.should_be == 'The server recieved your message'
+  end
+  
+  specify "class method 'call' should instantiate and call API" do
+    api = BaseApi.call(:message => 'Hello World!')
+    api.return_message.should_be == 'The server recieved your message'
+  end
+  
+  specify "'assert_success' should raise and exception on an error" do
+    BaseApi.url = 'http://test.com/base/error'
+    proc { BaseApi.call(:message => 'foo') }.should_raise RemoteAPI::ResponseFailure
+  end
+  
+end
+
+
+class BaseApi < RemoteAPI
+  attr_reader :return_message
+  
+  def request
+    x = Builder::XmlMarkup.new
+    x.my_request @message
+  end
+  
+  def assert_success
+    if @response =~ %r{<server_response>(.*error.*)</server_response>}
+      raise ResponseFailure, $1
+    end
+  end
+  
+  def process
+    @return_message = @response.gsub(%r{</?server_response>}, '')
+  end
+  
+end

data/{test/test_helper.rb → spec/spec_helper.rb}

@@ -1,5 +1,3 @@
-require 'test/unit'
-
 require 'rubygems'
 require 'fake_web'
 require 'builder'

data/spec/xml_response_spec.rb

@@ -0,0 +1,77 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+context "An XML Response object" do
+  
+  XML = <<XML
+<response>
+  <title>Test Title</title>
+  <items>
+    <item>
+      <name>Bob</name>
+      <id>1</id>
+    </item>
+    <item>
+      <name>Joe</name>
+      <id>2</id>
+    </item>
+    <item>
+      <name>Walter</name>
+      <id>3</id>
+    </item>
+  </items>
+</response>
+XML
+  
+  setup do
+    @xml = RemoteAPI::XML::Response.new(XML)
+  end
+  
+  specify "[] should accept XPath" do
+    @xml['//title'].should_be == "Test Title"
+  end
+  
+  specify "a bad XPath passed to [] should return nil" do
+    @xml['/foo/bar/baz'].should_be_nil
+  end
+  
+  specify "'each' with a bad XPath should not run provided block" do
+    count = 0
+    @xml.each('/foo/bar/baz') { |node| count += 1 }
+    count.should_be_zero
+  end
+  
+  specify "'each' should execute block for every matching XPath" do
+    expected_names = %w( Bob Joe Walter )
+    expected_ids   = %w( 1 2 3 )
+    count          = 0
+    
+    @xml.each "//items/item" do |node|
+      count += 1
+      node['name'].should_be == expected_names.shift
+      node['id'].should_be   == expected_ids.shift
+    end
+    
+    count.should_be == 3
+  end
+  
+  specify "calling 'each' without a block should raise an ArgumentError" do
+    proc {
+      @xml.each('//title')
+    }.should_raise ArgumentError
+  end
+  
+  specify "'to_formatted_s' should make the xml pretty" do
+    input = '<a><b><c>foo</c></b></a>'
+    expected = <<XML
+<a>
+  <b>
+    <c>foo</c>
+  </b>
+</a>
+XML
+    xml_response = RemoteAPI::XML::Response.new(input)
+    
+    xml_response.to_formatted_s.should_be == expected.chomp
+  end
+  
+end

data/{test/xml_test.rb → spec/xml_spec.rb}

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
+require File.dirname(__FILE__) + '/spec_helper'
 
 FakeWeb.register_uri(
   'http://test.com/xml', 
@@ -8,56 +8,54 @@ FakeWeb.register_uri(
   'http://test.com/xml/error', 
   :string => '<server_response><error>Big fat error</error></server_response>'
 )
+
+class XmlApi < RemoteAPI::XML
+  attr_reader :return_message
+  
+  def request
+    x = Builder::XmlMarkup.new
+    x.my_request @message
+  end
+  
+  def assert_success
+  	if error = @response['/server_response/error']
+      raise ResponseFailure, error
+    end
+  end
+  
+  def process
+    @return_message = @response['/foo/server_response']
+  end
+end
+
 
-class RemoteApiXMLTest < Test::Unit::TestCase
+context "An XML API" do
   
-  def setup
+  setup do
     XmlApi.url = 'http://test.com/xml'
   end
   
-  def test_response_should_be_xml
-    result = XmlApi.new(:message => 'foo')
-    assert_equal('The server recieved your message', result.return_message)
+  specify "response should be XML" do
+    result = XmlApi.call(:message => 'foo')
+    result.return_message.should_be == 'The server recieved your message'
   end
   
-  def test_format_response_should_produce_pretty_xml
+  specify "'format_response' should produce pretty xml" do
     expected = <<XML
 <foo>
   <server_response>The server recieved your message</server_response>
 </foo>
 XML
     
-    result = XmlApi.new(:message => 'foo')
-    data = result.send(:format_response, '<foo><server_response>The server recieved your message</server_response></foo>')
-    assert_equal(expected.chomp, data)
+    result = XmlApi.call(:message => 'foo')
+    data = result.send(:format_response, '<foo><server_response>The server recieved your message</server_response></foo>')
+    
+    data.should_be == expected.chomp
   end
   
-  def test_assert_success_should_raise_exceptions
+  specify "'assert_success' should raise an exception on failure" do
     XmlApi.url = 'http://test.com/xml/error'
-    assert_raise RemoteAPI::ResponseFailure do
-      XmlApi.new(:message => 'foo')
-    end
+    proc { XmlApi.call(:message => 'foo') }.should_raise RemoteAPI::ResponseFailure
   end
   
-end
-
-
-class XmlApi < RemoteAPI::XML
-  attr_reader :return_message
-  
-  def request
-    x = Builder::XmlMarkup.new
-    x.my_request @message
-  end
-  
-  def assert_success
-  	if error = @response['/server_response/error']
-      raise ResponseFailure, error
-    end
-  end
-  
-  def process
-    @return_message = @response['/foo/server_response']
-  end
-  
 end

data/test/spec_test.rb

@@ -0,0 +1,19 @@
+require 'test/unit'
+
+class SpecTest < Test::Unit::TestCase
+  def test_true
+    assert true
+  end
+end
+
+puts <<SPEC
+
+----------------------------------------------
+This gem has no tests.  Please run 'rake spec' 
+or 'rake spec_print' instead.
+
+The rspec gem must be installed to run specs.
+  gem install rspec
+----------------------------------------------
+
+SPEC

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.1
 specification_version: 1
 name: remote_api
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
-date: 2007-01-17 00:00:00 -08:00
+  version: 0.2.0
+date: 2007-04-19 00:00:00 -07:00
 summary: Provides a basic framework for easily creating classes that access remote APIs.
 require_paths: 
 - lib
@@ -39,14 +39,13 @@ files:
 - lib/remote_api/xml.rb
 - lib/remote_api/xml_response.rb
 - lib/remote_api/version.rb
-- test/test_helper.rb
-- test/base_test.rb
-- test/xml_test.rb
-- test/xml_response_test.rb
+- test/spec_test.rb
+- spec/base_spec.rb
+- spec/spec_helper.rb
+- spec/xml_response_spec.rb
+- spec/xml_spec.rb
 test_files: 
-- test/base_test.rb
-- test/xml_response_test.rb
-- test/xml_test.rb
+- test/spec_test.rb
 rdoc_options: []
 
 extra_rdoc_files: []

data/test/base_test.rb

@@ -1,58 +0,0 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-FakeWeb.register_uri(
-  'http://test.com/base', 
-  :string => '<server_response>The server recieved your message</server_response>'
-)
-FakeWeb.register_uri(
-  'http://test.com/base/error', 
-  :string => '<server_response>An error occurred!</server_response>'
-)
-
-class RemoteApiTest < Test::Unit::TestCase
-  
-  def setup
-    BaseApi.url = 'http://test.com/base'
-  end
-  
-  def test_initialize_should_set_hash_keys_as_instance_variables
-    result = BaseApi.new(:foo => 'bar', :baz => 'taz', :message => 'Hello')
-    
-    assert_equal('bar',   result.instance_eval { @foo })
-    assert_equal('taz',   result.instance_eval { @baz })
-    assert_equal('Hello', result.instance_eval { @message })
-  end
-  
-  def test_initialize_should_perform_api_call
-    result = BaseApi.new(:message => 'Hello World!')
-    assert_equal 'The server recieved your message', result.return_message
-  end
-  
-  def test_assert_success_should_raise_exception
-    BaseApi.url = 'http://test.com/base/error'
-    assert_raise RemoteAPI::ResponseFailure do
-      BaseApi.new(:message => 'foo')
-    end
-  end
-end
-
-
-class BaseApi < RemoteAPI
-  attr_reader :return_message
-  
-  def request
-    x = Builder::XmlMarkup.new
-    x.my_request @message
-  end
-  
-  def assert_success
-    if @response =~ %r{<server_response>(.*error.*)</server_response>}
-      raise ResponseFailure, $1
-    end
-  end
-  
-  def process
-    @return_message = @response.gsub(%r{</?server_response>}, '')
-  end
-  
-end

data/test/xml_response_test.rb

@@ -1,77 +0,0 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-class XmlResponseTest < Test::Unit::TestCase
-  
-  XML = <<XML
-<response>
-  <title>Test Title</title>
-  <items>
-    <item>
-      <name>Bob</name>
-      <id>1</id>
-    </item>
-    <item>
-      <name>Joe</name>
-      <id>2</id>
-    </item>
-    <item>
-      <name>Walter</name>
-      <id>3</id>
-    </item>
-  </items>
-</response>
-XML
-  
-  def setup
-    @xml = RemoteAPI::XML::Response.new(XML)
-  end
-  
-  def test_brace_accessor
-    assert_equal('Test Title', @xml['//title'])
-  end
-  
-  def test_bad_xpath_should_return_nil
-    assert_nil @xml['/foo/bar/baz']
-  end
-  
-  def test_each_on_bad_xpath_should_not_run_block
-    count = 0
-    @xml.each('/foo/bar/baz') { |node| count += 1 }
-    assert_equal(0, count)
-  end
-  
-  def test_each
-    expected_names = %w( Bob Joe Walter )
-    expected_ids   = %w( 1 2 3 )
-    count          = 0
-    
-    @xml.each '//items/item' do |node|
-      count += 1
-      assert_equal(expected_names.shift, node['name'])
-      assert_equal(expected_ids.shift,   node['id'])
-    end
-    
-    assert_equal(3, count)
-  end
-  
-  def test_each_without_block_should_raise_exception
-    assert_raise(ArgumentError) do
-      @xml.each('//title')
-    end
-  end
-  
-  def test_to_formatted_s
-    input = '<a><b><c>foo</c></b></a>'
-    expected = <<XML
-<a>
-  <b>
-    <c>foo</c>
-  </b>
-</a>
-XML
-    xml_response = RemoteAPI::XML::Response.new(input)
-    
-    assert_equal(expected.chomp, xml_response.to_formatted_s)
-  end
-  
-end