Remote API

Rubyforge Project: rubyforge.org/projects/remote-api/ Installation: <code>gem install remote_api

Overview

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.

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:

  require 'remote_api'

  class Shipment < RemoteAPI
    attr_reader :tracking_number
    url 'http://test.com/shipments'

    def request
      <<-EOF
        address: #{@address}
        weight: #{@weight}
      EOF
    end

    def assert_success
      raise ResponseFailure if @response =~ /error/
    end

    def process
      @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 @address and @weight 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 @response variable. This all happens automatically.

Assertion of Success

Most API‘s have some sort of error reporting. The assert_success 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 attr_reader 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}"

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

  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

README.txt