dambalah-twitter4r 0.3.1

data/lib/twitter/client/friendship.rb

@@ -0,0 +1,47 @@
+class Twitter::Client
+  @@FRIENDSHIP_URIS = {
+    :add => '/friendships/create',
+    :remove => '/friendships/destroy',
+    :exists => '/friendships/exists'    
+  }
+	
+  # Provides access to the Twitter Friendship API.
+  # 
+  # You can add and remove friends using this method.
+  # 
+  # <tt>action</tt> can be any of the following values:
+  # * <tt>:add</tt> - to add a friend, you would use this <tt>action</tt> value
+  # * <tt>:remove</tt> - to remove an existing friend from your friends list use this.
+  # 
+  # The <tt>value</tt> must be either the user to befriend or defriend's 
+  # screen name, integer unique user ID or Twitter::User object representation.
+  # 
+  # Examples:
+  #  screen_name = 'dictionary'
+  #  client.friend(:add, 'dictionary')
+  #  client.friend(:remove, 'dictionary')
+  #  id = 1260061
+  #  client.friend(:add, id)
+  #  client.friend(:remove, id)
+  #  user = Twitter::User.find(id, client)
+  #  client.friend(:add, user)
+  #  client.friend(:remove, user)
+  def friend(action, value)
+    raise ArgumentError, "Invalid friend action provided: #{action}" unless @@FRIENDSHIP_URIS.keys.member?(action)
+    value = value.to_i unless value.is_a?(String)
+    uri = "#{@@FRIENDSHIP_URIS[action]}/#{value}.json"
+    response = http_connect {|conn| create_http_post_request(uri) }
+    bless_model(Twitter::User.unmarshal(response.body))
+  end
+  
+  # Tests if a friendship exists between two users.
+  # 
+  # Examples:
+  #   client.are_friends?(user1,user2)  #=> returns true if user1 follows user2
+  #                                     #=> returns false if user1 does not follower user2   
+  def are_friends?(user1,user2)
+    uri = "#{@@FRIENDSHIP_URIS[:exists]}.json?user_a=#{user1}&user_b=#{user2}"
+    response = http_connect {|conn| create_http_post_request(uri) }
+    response.body.rindex('true') ? true : false
+  end  
+end

data/lib/twitter/client/messaging.rb

@@ -0,0 +1,79 @@
+class Twitter::Client
+
+  @@MESSAGING_URIS = {
+    :received => '/direct_messages.json',
+    :sent => '/direct_messages/sent.json',
+    :post => '/direct_messages/new.json',
+    :delete => '/direct_messages/destroy',
+  }
+
+  # Provides access to Twitter's Messaging API for received and 
+  # sent direct messages.
+  # 
+  # Example:
+  #  received_messages = @twitter.messages(:received)
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:received+
+  # * +:sent+
+  def messages(action, options = {})
+    raise ArgumentError, "Invalid messaging action: #{action}" unless [:sent, :received].member?(action)
+    uri = @@MESSAGING_URIS[action]
+    response = http_connect {|conn|	create_http_get_request(uri, options) }
+    bless_models(Twitter::Message.unmarshal(response.body))
+  end
+  
+  # Provides access to Twitter's Messaging API for sending and deleting 
+  # direct messages to other users.
+  # 
+  # <tt>action</tt> can be:
+  # * <tt>:post</tt> - to send a new direct message, <tt>value</tt>, to <tt>user</tt> given.
+  # * <tt>:delete</tt> - to delete direct message with message ID <tt>value</tt>.
+  # 
+  # <tt>value</tt> should be:
+  # * <tt>String</tt> when action is <tt>:post</tt>.  Will be the message text sent to given <tt>user</tt>.
+  # * <tt>Integer</tt> or <tt>Twitter::Message</tt> object when action is <tt>:delete</tt>.  Will refer to the unique message ID to delete.  When passing in an instance of <tt>Twitter::Message</tt> that Status will be 
+  # 
+  # <tt>user</tt> should be:
+  # * <tt>Twitter::User</tt>, <tt>Integer</tt> or <tt>String</tt> object when <tt>action</tt> is <tt>:post</tt>.  The <tt>Integer</tt> must be the unique ID of the Twitter user you wish to send the direct message to and any <tt>String</tt>s passed in must be the screen name of the user you wish to send the direct message to.
+  # * totally ignore when <tt>action</tt> is <tt>:delete</tt>.  It has no purpose in this use case scenario.
+  # 
+  # Examples:
+  # The example below sends the message text 'Are you coming over at 6pm for the BBQ tonight?' to user with screen name 'myfriendslogin'...
+  #  @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', 'myfriendslogin')
+  # The example below sends the same message text as above to user with unique integer ID of 1234567890...
+  # the example below sends the same message text as above to user represented by <tt>user</tt> object instance of <tt>Twitter::User</tt>...
+  #  @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', user)
+  #  message = @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', 1234567890)
+  # the example below delete's the message send directly above to user with unique ID 1234567890...
+  #  @twitter.message(:delete, message)
+  # Or the following can also be done...
+  #  @twitter.message(:delete, message.id)
+  # 
+  # In both scenarios (<tt>action</tt> is <tt>:post</tt> or 
+  # <tt>:delete</tt>) a blessed <tt>Twitter::Message</tt> object is 
+  # returned that represents the newly posted or newly deleted message.
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:post+
+  # * +:delete+
+  # 
+  # An <tt>ArgumentError</tt> is also raised when no user argument is 
+  # supplied when <tt>action</tt> is +:post+.
+  def message(action, value, user = nil)
+    raise ArgumentError, "Invalid messaging action: #{action}" unless [:post, :delete].member?(action)
+    raise ArgumentError, "User argument must be supplied for :post case" if action.eql?(:post) and user.nil?
+    uri = @@MESSAGING_URIS[action]
+    user = user.to_i if user and user.is_a?(Twitter::User)
+    case action
+    when :post
+      response = http_connect({:text => value, :user => user, :source => @@config.source}.to_http_str) {|conn| create_http_post_request(uri) }
+    when :delete
+      response = http_connect {|conn| create_http_delete_request(uri, :id => value.to_i) }
+    end
+    message = Twitter::Message.unmarshal(response.body)
+    bless_model(message)
+  end
+end

data/lib/twitter/client/status.rb

@@ -0,0 +1,46 @@
+class Twitter::Client
+  @@STATUS_URIS = {
+  	:get => '/statuses/show.json',
+  	:post => '/statuses/update.json',
+  	:delete => '/statuses/destroy.json',
+  }
+  
+  # Provides access to individual statuses via Twitter's Status APIs
+  # 
+  # <tt>action</tt> can be of the following values:
+  # * <tt>:get</tt> to retrieve status content.  Assumes <tt>value</tt> given responds to :to_i message in meaningful way to yield intended status id.
+  # * <tt>:post</tt> to publish a new status
+  # * <tt>:delete</tt> to remove an existing status.  Assumes <tt>value</tt> given responds to :to_i message in meaningful way to yield intended status id.
+  # 
+  # <tt>value</tt> should be set to:
+  # * the status identifier for <tt>:get</tt> case
+  # * the status text message for <tt>:post</tt> case
+  # * none necessary for <tt>:delete</tt> case
+  # 
+  # Examples:
+  #  twitter.status(:get, 107786772)
+  #  twitter.status(:post, "New Ruby open source project Twitter4R version 0.2.0 released.")
+  #  twitter.status(:delete, 107790712)
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:get+
+  # * +:post+
+  # * +:delete+
+  def status(action, value = nil)
+    return self.timeline_for(action, value || {}) if :replies == action
+    raise ArgumentError, "Invalid status action: #{action}" unless @@STATUS_URIS.keys.member?(action)
+    return nil unless value
+  	uri = @@STATUS_URIS[action]
+  	response = nil
+    case action
+    when :get
+    	response = http_connect {|conn|	create_http_get_request(uri, :id => value.to_i) }
+    when :post
+    	response = http_connect({:status => value, :source => @@config.source}.to_http_str) {|conn| create_http_post_request(uri) }
+    when :delete
+    	response = http_connect {|conn| create_http_delete_request(uri, :id => value.to_i) }
+    end
+    bless_model(Twitter::Status.unmarshal(response.body))
+  end
+end

data/lib/twitter/client/timeline.rb

@@ -0,0 +1,72 @@
+class Twitter::Client
+  @@TIMELINE_URIS = {
+    :public => '/statuses/public_timeline.json',
+    :friends => '/statuses/friends_timeline.json',
+    :friend => '/statuses/friends_timeline.json',
+    :user => '/statuses/user_timeline.json',
+    :me => '/statuses/user_timeline.json',
+    :replies => '/statuses/replies.json',
+  }
+
+  # Provides access to Twitter's Timeline APIs
+  # 
+  # Returns timeline for given <tt>type</tt>.  
+  # 
+  # <tt>type</tt> can take the following values:
+  # * <tt>public</tt>
+  # * <tt>friends</tt> or <tt>friend</tt>
+  # * <tt>user</tt> or <tt>me</tt>
+  # 
+  # <tt>:id</tt> is on key applicable to be defined in </tt>options</tt>:
+  # * the id or screen name (aka login) for :friends
+  # * the id or screen name (aka login) for :user
+  # * meaningless for the :me case, since <tt>twitter.timeline_for(:user, 'mylogin')</tt> and <tt>twitter.timeline_for(:me)</tt> are the same assuming 'mylogin' is the authenticated user's screen name (aka login).
+  # 
+  # Examples:
+  #  # returns the public statuses since status with id of 6543210
+  #  twitter.timeline_for(:public, id => 6543210)
+  #  # returns the statuses for friend with user id 43210
+  #  twitter.timeline_for(:friend, :id => 43210)
+  #  # returns the statuses for friend with screen name (aka login) of 'otherlogin'
+  #  twitter.timeline_for(:friend, :id => 'otherlogin')
+  #  # returns the statuses for user with screen name (aka login) of 'otherlogin'
+  #  twitter.timeline_for(:user, :id => 'otherlogin')
+  # 
+  # <tt>options</tt> can also include the following keys:
+  # * <tt>:id</tt> is the user ID, screen name of Twitter::User representation of a <tt>Twitter</tt> user.
+  # * <tt>:since</tt> is a Time object specifying the date-time from which to return results for.  Applicable for the :friend, :friends, :user and :me cases.
+  # * <tt>:count</tt> specifies the number of statuses to retrieve.  Only applicable for the :user case.
+  # * <tt>since_id</tt> is the status id of the public timeline from which to retrieve statuses for <tt>:public</tt>.  Only applicable for the :public case.
+  # 
+  # You can also pass this method a block, which will iterate through the results
+  # of the requested timeline and apply the block logic for each status returned.
+  # 
+  # Example:
+  #  twitter.timeline_for(:public) do |status|
+  #    puts status.user.screen_name, status.text
+  #  end
+  #  
+  #  twitter.timeline_for(:friend, :id => 'myfriend', :since => 30.minutes.ago) do |status|
+  #    puts status.user.screen_name, status.text
+  #  end
+  #  
+  #  timeline = twitter.timeline_for(:me) do |status|
+  #    puts status.text
+  #  end
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>type</tt> 
+  # is given.  Valid types are:
+  # * +:public+
+  # * +:friends+
+  # * +:friend+
+  # * +:user+
+  # * +:me+
+  def timeline_for(type, options = {}, &block)
+    raise ArgumentError, "Invalid timeline type: #{type}" unless @@TIMELINE_URIS.keys.member?(type)
+    uri = @@TIMELINE_URIS[type]
+    response = http_connect {|conn| create_http_get_request(uri, options) }
+    timeline = Twitter::Status.unmarshal(response.body)
+    timeline.each {|status| bless_model(status); yield status if block_given? }
+    timeline
+  end
+end

data/lib/twitter/client/user.rb

@@ -0,0 +1,87 @@
+class Twitter::Client
+  @@USER_URIS = {
+  	:info => '/users/show',
+  	:friends => '/statuses/friends.json',
+  	:followers => '/statuses/followers.json',
+  }
+  
+  # Provides access to Twitter's User APIs
+  # 
+  # Returns user instance for the <tt>id</tt> given.  The <tt>id</tt>
+  # can either refer to the numeric user ID or the user's screen name.
+  # 
+  # For example,
+  #  @twitter.user(234943) #=> Twitter::User object instance for user with numeric id of 234943
+  #  @twitter.user('mylogin') #=> Twitter::User object instance for user with screen name 'mylogin'
+  # 
+  # Where <tt>options</tt> is a +Hash+ of options that can include:
+  # * <tt>:page</tt> - optional.  Retrieves the next set of friends.  There are 100 friends per page.  Default: 1.
+  # * <tt>:lite</tt> - optional.  Prevents the inline inclusion of current status.  Default: false.
+  # * <tt>:since</tt> - optional.  Only relevant for <tt>:friends</tt> action.  Narrows the results to just those friends added after the date given as value of this option.  Must be HTTP-formatted date.
+  #
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:info+
+  # * +:friends+
+  # 
+  # +Note:+ You should not use this method to attempt to retrieve the 
+  # authenticated user's followers.  Please use any of the following 
+  # ways of accessing this list:
+  #  followers = client.my(:followers)
+  # OR
+  #  followers = client.my(:info).followers
+  def user(id, action = :info, options = {})
+    raise ArgumentError, "Invalid user action: #{action}" unless @@USER_URIS.keys.member?(action)
+    id = id.to_i if id.is_a?(Twitter::User)
+    params = options.merge(:id => id)
+    response = http_connect {|conn| create_http_get_request(@@USER_URIS[action], params) }
+    bless_models(Twitter::User.unmarshal(response.body))
+  end
+  
+  # Syntactic sugar for queries relating to authenticated user in Twitter's User API
+  # 
+  # Where <tt>action</tt> is one of the following:
+  # * <tt>:info</tt> - Returns user instance for the authenticated user.
+  # * <tt>:friends</tt> - Returns Array of users that are authenticated user's friends
+  # * <tt>:followers</tt> - Returns Array of users that are authenticated user's followers
+  # 
+  # Where <tt>options</tt> is a +Hash+ of options that can include:
+  # * <tt>:page</tt> - optional.  Retrieves the next set of friends.  There are 100 friends per page.  Default: 1.
+  # * <tt>:lite</tt> - optional.  Prevents the inline inclusion of current status.  Default: false.
+  # * <tt>:since</tt> - optional.  Only relevant for <tt>:friends</tt> action.  Narrows the results to just those friends added after the date given as value of this option.  Must be HTTP-formatted date.
+  #
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:info+
+  # * +:friends+
+  # * +:followers+
+  def my(action, options = {})
+    raise ArgumentError, "Invalid user action: #{action}" unless @@USER_URIS.keys.member?(action)
+    params = options.merge(:id => @login)
+    response = http_connect {|conn| create_http_get_request(@@USER_URIS[action], params) }
+    users = Twitter::User.unmarshal(response.body)
+    bless_models(users)
+  end
+  
+  # Returns all followers for an authenticated user.
+  #
+  # This method makes multiple call to the Twitter API to get all users.
+  # By default, the Twitter API only returns 100 followers at a time.
+  # This method was written for the case where you need all followers,no matter how many there are.
+  #
+  def all_followers
+    has_followers_remaining = true
+    followers_array = []
+    page = 1
+    while has_followers_remaining
+      tmp_followers = self.my(:followers, :page => page)
+      followers_array << tmp_followers
+      #puts "Page: #{page} , followers: #{tmp_followers.size}"
+      page += page
+      has_followers_remaining = false unless tmp_followers.size > 98
+      sleep 1
+    end
+    followers_array.flatten! 
+  end
+  
+end

data/lib/twitter/config.rb

@@ -0,0 +1,71 @@
+# config.rb contains classes, methods and extends existing Twitter4R classes 
+# to provide easy configuration facilities.
+
+module Twitter
+  # Represents global configuration for Twitter::Client.
+  # Can override the following configuration options:
+  # * <tt>protocol</tt> - <tt>:http</tt>, <tt>:https</tt> or <tt>:ssl</tt> supported.  <tt>:ssl</tt> is an alias for <tt>:https</tt>.  Defaults to <tt>:ssl</tt>
+  # * <tt>host</tt> - hostname to connect to for the Twitter service.  Defaults to <tt>'twitter.com'</tt>.
+  # * <tt>port</tt> - port to connect to for the Twitter service.  Defaults to <tt>443</tt>.
+  # * <tt>proxy_host</tt> - proxy host to use.  Defaults to nil.
+  # * <tt>proxy_port</tt> - proxy host to use.  Defaults to nil.
+  # * <tt>proxy_user</tt> - proxy username to use.  Defaults to nil.
+  # * <tt>proxy_pass</tt> - proxy password to use.  Defaults to nil.
+  # * <tt>user_agent</tt> - user agent string to use for each request of the HTTP header.
+  # * <tt>application_name</tt> - name of your client application.  Defaults to 'Twitter4R'
+  # * <tt>application_version</tt> - version of your client application.  Defaults to current <tt>Twitter::Version.to_version</tt>.
+  # * <tt>application_url</tt> - URL of your client application.  Defaults to http://twitter4r.rubyforge.org.
+  # * <tt>source</tt> - the source id given to you by Twitter to identify your application in their web interface.  Note: you must contact Twitter.com developer directly so they can configure their servers appropriately.
+  class Config
+    include ClassUtilMixin
+    @@ATTRIBUTES = [
+      :protocol, 
+      :host, 
+      :port, 
+      :proxy_host, 
+      :proxy_port, 
+      :proxy_user, 
+      :proxy_pass, 
+      :user_agent,
+      :application_name,
+      :application_version,
+      :application_url,
+      :source,
+    ]
+    attr_accessor *@@ATTRIBUTES
+    
+    # Override of Object#eql? to ensure RSpec specifications run 
+    # correctly. Also done to follow Ruby best practices.
+    def eql?(other)
+      return true if self == other
+      @@ATTRIBUTES.each do |att|
+        return false unless self.send(att).eql?(other.send(att))
+      end
+      true
+    end
+  end
+
+  class Client
+    @@defaults = { :host => 'twitter.com', 
+                   :port => 443, 
+                   :protocol => :ssl,
+                   :proxy_host => nil,
+                   :proxy_port => nil,
+                   :user_agent => "default",
+                   :application_name => 'Twitter4R',
+                   :application_version => Twitter::Version.to_version,
+                   :application_url => 'http://twitter4r.rubyforge.org',
+                   :source => 'sharememe',
+    }
+    @@config = Twitter::Config.new(@@defaults)
+
+    # Twitter::Client class methods
+    class << self
+      # Yields to given <tt>block</tt> to configure the Twitter4R API.
+      def configure(&block)
+        raise ArgumentError, "Block must be provided to configure" unless block_given?
+        yield @@config
+      end # configure
+    end # class << self    
+  end # Client class
+end # Twitter module

data/lib/twitter/console.rb

@@ -0,0 +1,28 @@
+# Contains hooks for the twitter console
+
+module Twitter
+  class Client
+    class << self
+      # Helper method mostly for irb shell prototyping.
+      # 
+      # Reads in login/password Twitter credentials from YAML file
+      # found at the location given by <tt>config_file</tt> that has 
+      # the following format:
+      #  envname:
+      #    login: mytwitterlogin
+      #    password: mytwitterpassword
+      # 
+      # Where <tt>envname</tt> is the name of the environment like 'test', 
+      # 'dev' or 'prod'.  The <tt>env</tt> argument defaults to 'test'.
+      # 
+      # To use this in the shell you would do something like the following 
+      # examples:
+      #  twitter = Twitter::Client.from_config('config/twitter.yml', 'dev')
+      #  twitter = Twitter::Client.from_config('config/twitter.yml')
+      def from_config(config_file, env = 'test')
+        yaml_hash = YAML.load(File.read(config_file))
+        self.new yaml_hash[env]
+      end
+    end # class << self
+  end
+end

data/lib/twitter/core.rb

@@ -0,0 +1,137 @@
+# The Twitter4R API provides a nicer Ruby object API to work with 
+# instead of coding around the REST API.
+
+# Module to encapsule the Twitter4R API.
+module Twitter
+  # Mixin module for classes that need to have a constructor similar to
+  # Rails' models, where a <tt>Hash</tt> is provided to set attributes
+  # appropriately.
+  # 
+  # To define a class that uses this mixin, use the following code:
+  #  class FilmActor
+  #    include ClassUtilMixin
+  #  end
+  module ClassUtilMixin #:nodoc:
+    def self.included(base) #:nodoc:
+      base.send(:include, InstanceMethods)
+    end
+    
+    # Instance methods defined for <tt>Twitter::ModelMixin</tt> module.
+    module InstanceMethods #:nodoc:
+      # Constructor/initializer that takes a hash of parameters that 
+      # will initialize *members* or instance attributes to the 
+      # values given.  For example,
+      # 
+      #  class FilmActor
+      #    include Twitter::ClassUtilMixin
+      #    attr_accessor :name
+      #  end
+      #  
+      #  class Production
+      #    include Twitter::ClassUtilMixin
+      #    attr_accessor :title, :year, :actors
+      #  end
+      #  
+      #  # Favorite actress...
+      #  jodhi = FilmActor.new(:name => "Jodhi May")
+      #  jodhi.name # => "Jodhi May"
+      #  
+      #  # Favorite actor...
+      #  robert = FilmActor.new(:name => "Robert Lindsay")
+      #  robert.name # => "Robert Lindsay"
+      #  
+      #  # Jane is also an excellent pick...gotta love her accent!
+      #  jane = FilmActor.new(name => "Jane Horrocks")
+      #  jane.name # => "Jane Horrocks"
+      #  
+      #  # Witty BBC series...
+      #  mrs_pritchard = Production.new(:title => "The Amazing Mrs. Pritchard", 
+      #                                 :year => 2005, 
+      #                                 :actors => [jodhi, jane])
+      #  mrs_pritchard.title  # => "The Amazing Mrs. Pritchard"
+      #  mrs_pritchard.year   # => 2005
+      #  mrs_pritchard.actors # => [#<FilmActor:0xb79d6bbc @name="Jodhi May">, 
+      #  <FilmActor:0xb79d319c @name="Jane Horrocks">]
+      #  # Any Ros Pritchard's out there to save us from the Tony Blair
+      #  # and Gordon Brown *New Labour* debacle?  You've got my vote! 
+      #  
+      #  jericho = Production.new(:title => "Jericho", 
+      #                           :year => 2005, 
+      #                           :actors => [robert])
+      #  jericho.title   # => "Jericho"
+      #  jericho.year    # => 2005
+      #  jericho.actors  # => [#<FilmActor:0xc95d3eec @name="Robert Lindsay">]
+      # 
+      # Assuming class <tt>FilmActor</tt> includes 
+      # <tt>Twitter::ClassUtilMixin</tt> in the class definition 
+      # and has an attribute of <tt>name</tt>, then that instance 
+      # attribute will be set to "Jodhi May" for the <tt>actress</tt> 
+      # object during object initialization (aka construction for 
+      # you Java heads).
+      def initialize(params = {})
+        params.each do |key,val|
+          self.send("#{key}=", val) if self.respond_to? key
+        end
+        self.send(:init) if self.respond_to? :init
+      end
+      
+      protected
+        # Helper method to provide an easy and terse way to require 
+        # a block is provided to a method.
+        def require_block(block_given)
+          raise ArgumentError, "Must provide a block" unless block_given
+        end
+    end
+  end # ClassUtilMixin
+  
+  # Exception subclass raised when there is an error encountered upon 
+  # querying or posting to the remote Twitter REST API.
+  # 
+  # To consume and query any <tt>RESTError</tt> raised by Twitter4R:
+  #  begin
+  #    # Do something with your instance of <tt>Twitter::Client</tt>.
+  #    # Maybe something like:
+  #    timeline = twitter.timeline_for(:public)
+  #  rescue RESTError => re
+  #    puts re.code, re.message, re.uri
+  #  end
+  # Which on the code raising a <tt>RESTError</tt> will output something like:
+  #  404
+  #  Resource Not Found
+  #  /i_am_crap.json
+  class RESTError < Exception
+    include ClassUtilMixin
+    @@ATTRIBUTES = [:code, :message, :uri]
+    attr_accessor :code, :message, :uri
+    
+    # Returns string in following format:
+    #  "HTTP #{@code}: #{@message} at #{@uri}"
+    # For example,
+    #  "HTTP 404: Resource Not Found at /i_am_crap.json"
+    def to_s
+      "HTTP #{@code}: #{@message} at #{@uri}"
+    end
+  end # RESTError
+  
+  # Remote REST API interface representation
+  # 
+  class RESTInterfaceSpec
+  	include ClassUtilMixin
+  	
+  end
+  
+  # Remote REST API method representation
+  # 
+  class RESTMethodSpec
+  	include ClassUtilMixin
+  	attr_accessor :uri, :method, :parameters
+  end
+  
+  # Remote REST API method parameter representation
+  # 
+  class RESTParameterSpec
+  	include ClassUtilMixin
+  	attr_accessor :name, :type, :required
+  	def required?; @required; end
+  end
+end