yanapi 0.1.1 → 0.3.1

data/CHANGELOG

@@ -0,0 +1,22 @@
+=== COMPLETED
+==== 0.3.1
+All four search methods implemented.
+==== 0.1.1
+Small fixes in the documentation.
+==== 0.1.0
+The search methods <tt>questionSearch</tt> and <tt>getByCategory</tt>.
+==== 0.0.1
+Initial release of the lib.
+
+
+=== PLANNED
+==== 0.4.0
+Enhance the documentation.
+
+Implement multivalue parameters.
+==== 0.5.0
+==== 0.6.0
+==== 0.7.0
+==== 0.8.0
+==== 0.9.0
+==== 1.0.0

data/README

@@ -1,12 +1,94 @@
-YANAPI is a Yahoo! Answers API written in Ruby.
+= YANAPI
 
-Example:
+* {RubyGems}[http://rubygems.org/gems/yanapi]
+* Developers {Homepage}[http://www.uni-trier.de/index.php?id=24140]
+* {YANAPI Project Page}[http://yanapi.rubyforge.org/]
 
-require 'rubygems'
-require 'yanapi'
+== DESCRIPTION
 
-params = {:appid => 'YahooDemo', :query => 'car'}
+YANAPI is an API for Yahoo! Answers web services. It has been developed
+in {Ruby}[http://www.ruby-lang.org].
 
-query = YANAPI::TermQuery.new(params)
+YANAPI provides a flexible interface to the {Yahoo! Answers}[http://answers.yahoo.com/] search services.
 
-query.get
+It supports four search types:
+* key word search;
+* search based on the category name or the category ID;
+* search for a precise question ID;
+* search for a questions posted by a user with an ID.
+
+It is possible to restrict key word based search through a category.
+
+Question Search and User Search cannot be extended by key words or category IDs.
+
+Yanapi tries to as flexible as possible. It restricts unallowed parameter
+combinations and forces using mandatory ones. But it doesn't care about defaults.
+For example, as for this writing the default output value is an xml based format.
+If it changes in the future, the user will be responsible to choose the format.
+No defaults are hardcoded in YANAPI.
+YANAPI provides the minimal acceptable query. 
+
+== SYNOPSIS
+
+YANAPI requires a parameter hash with two dimensions:
+* the key +:method+ points to one of possible search methods
+  (<tt>'questionSearch', 'getByCategory', 'getByUser', 'getQuestion'</tt>);
+* the key +:query_params+ points to a parameter hash, the names of the parameters
+  and their values correspond to the semantics given
+  on {the official page}[http://developer.yahoo.com/answers/];
+* values in +:query_params+ may be +String+, +Fixnum+ or +Array+, the latter
+  provides the opportunity for multiple values which is possible and sometimes
+  reasonable for such keys as +:region+, +:category_id+ or +:category_name+.
+
+A small example shall demostrate the usage:
+  require 'yanapi'
+  params = {
+    :method => 'questionSearch',
+    :query_params => {
+      :appid => 'YahooDemo',
+      :query => 'Haus',
+      :search_in => 'question',
+      :type => 'resolved',
+      :results => 2,
+      :output => 'xml'
+    }
+  }
+  api = YANAPI::API.new(params)
+  api.get # => default xml structure
+
+
+For details on particular keys and defaults see {the official description}[http://developer.yahoo.com/answers/] and the RDoc documentation in this libruary.
+
+== EXCEPTION HIERARCHY
+While using YANAPI you can face three kinds of errors:
+* <tt>YANAPI::UserError</tt>;
+* <tt>YANAPI::ExternalError</tt>;
+* <tt>YANAPI::ContentError</tt>.
+
+See the RDoc documentation on semantics of these errors.
+
+All of them are subcalsses of <tt>YANAPI::Error</tt> which is in turn a subclass
+of the standard +RuntimeError+.
+
+If you want to intercept any and every exception thrown by YANAPI simply rescue
+<tt>YANAPI::Error</tt>.
+
+== SEARCH STRATEGIES
+This section will describe possible applications of YANAPI.
+
+== CHANGELOG
+See CHANGELOG.
+
+== CAUTION
+This library is <b>work in process</b>! Though the interface is mostly complete,
+you might face some not implemented features.
+
+Please contact me with your suggestions, bug reports and feature requests.
+
+
+
+== LICENSE
+
+YANAPI is a copyrighted software by Andrei Beliankou, 2011.
+You may use, redistribute and change it under the terms
+provided in the LICENSE file.

data/lib/yanapi.rb

@@ -1,8 +1,2 @@
-require 'yanapi/common'
-require 'yanapi/query'
-require 'yanapi/term_query'
-require 'yanapi/question_query'
-require 'yanapi/user_query'
-require 'yanapi/category_query'
-require 'yanapi/version'
+require 'yanapi/api'
 

data/lib/yanapi/api.rb

@@ -0,0 +1,97 @@
+# :title: YANAPI, Yahoo! Answers API
+# :main: README.rdoc
+
+require 'yanapi/version'
+require 'yanapi/term_query'
+require 'yanapi/category_query'
+require 'yanapi/user_query'
+require 'yanapi/question_query'
+
+module YANAPI
+  class API
+    REQUIRED_PARAMS = [:method, :query_params]
+    ACCEPTED_METHODS = ['questionSearch',
+                       'getByUser',
+                       'getByCategory',
+                       'getQuestion'
+                       ]
+
+    def initialize(params)
+
+      @params = check_params(params)
+      
+      @query = case @params[:method]
+               when 'questionSearch'
+                 TermQuery.new(@params)
+               when 'getByCategory'
+                 CategoryQuery.new(@params)
+               when 'getByUser'
+                 UserQuery.new(@params)
+               when 'getQuestion'
+                 QuestionQuery.new(@params)
+               end
+    end
+    
+    # This is a connector to the specific method in the query.
+    def get
+      @query.get
+    end
+
+    def version
+      VERSION
+    end
+
+    private
+    def check_params(params)
+      # It should be an instance on non empty hash.
+      unless params.instance_of?(Hash)
+        fail(UserError, "Params should be a Hash, not #{params.class}!")
+      end
+
+      if params.empty?
+        fail(UserError, 'The params hash is empty!')        
+      end
+
+      # It should contain required keys and be two dimensional.
+      missed_keys = []
+      REQUIRED_PARAMS.each do |key|
+        unless params.has_key?(key)
+          missed_keys << key
+        end
+      end
+      unless missed_keys.empty?
+        fail(UserError,
+             "You should provide: <:#{missed_keys.join('>, <:')}>!")
+      end
+
+      unless params[:query_params].instance_of?(Hash)
+        key = params[:query_params]
+        fail(UserError,
+             "<:query_params> should be a Hash, not #{key.class}!")
+      end
+
+      if params[:query_params].empty?
+        fail(UserError, '<:query_params> is empty!')        
+      end
+
+      # It should accept only allowed methods.
+      unless ACCEPTED_METHODS.include?(params[:method])
+        fail(UserError,
+             "<#{params[:method]}> is not a valid search method!")
+      end
+
+      # It should warn about superfluous keys.
+      superfluous_keys = []
+      params.each_key do |key|
+        unless REQUIRED_PARAMS.include?(key)
+          superfluous_keys <<  key
+        end
+      end
+      unless superfluous_keys.empty?
+        warn "Keys ignored: <:#{superfluous_keys.join('>, <:')}>!"
+      end
+      
+      params
+    end
+  end
+end

data/lib/yanapi/category_query.rb

@@ -1,8 +1,21 @@
+require 'yanapi/query'
+require 'yanapi/common'
 
 module YANAPI
   
   class CategoryQuery < Query
-
+    VALID_PARAMS = [:category_id,
+                     :category_name,
+                     :date_range,
+                     :region,
+                     :results,
+                     :sort,
+                     :start,
+                     :type
+                    ]
+    # Semantics differ here: OR, not AND.
+    REQUIRED_PARAMS = [[:category_id, :category_name]]
+    
     include Common
     
     def initialize(params)

data/lib/yanapi/error.rb

@@ -34,4 +34,7 @@ module YANAPI
   # we are out of the response range (but we are under the :start limitations).
   class EmptyResponse < Error
   end
+
+  class UserError < Error
+  end
 end # YANAPI

data/lib/yanapi/query.rb

@@ -1,5 +1,4 @@
 # This code is based on ideas from "rc_rest" and "yahoo" gems.
-# gem install nokogiri
 require 'nokogiri'
 require 'net/http'
 require 'uri'
@@ -12,19 +11,18 @@ module YANAPI
     HOST = 'http://answers.yahooapis.com'
     SERVICE = 'AnswersService'
     SERVICE_VERSION = 'V1'
-
-    attr_accessor :output, :url
+    VALID_PARAMS = [:appid, :output, :callback]
+    REQUIRED_PARAMS = [:appid]
+    VALID_OUTPUT_FORMATS = [nil, 'xml', 'php', 'rss', 'json']
     
+    # It accepts a two dimensional hash:
+    # {:method => 'questionSearch', :query_params =>
+    #   {:appid => 'YahooDemo', :query => 'Haus'}}
     def initialize(params)
-      # xml|json|php|rss
-      @output = params[:output] || 'xml'
-      
-      # it is a bad idea to alter the parameters hash
-      # that's why we duplicate the parameters
-      check_params(params)
-      @url = build_url(params.dup)
-            
-      $stderr.puts 'Full url:', @url if $DEBUG
+      @method = params[:method]
+      @params = check_params(params[:query_params])
+      @url = build_url(@params)
+      @output = @params[:output] || 'xml'            
     end
     
     # main method
@@ -34,33 +32,27 @@ module YANAPI
       case @output
       when 'xml'
         # Set the value to STRICT (0), otherwise no errors will be raised!
-        result = Nokogiri::XML::Document.parse(http_response.body, nil, nil, 0)
-        prove_xml(result)
+        xml = Nokogiri::XML::Document.parse(http_response.body, nil, nil, 0)
+        result = prove_xml(xml) ? http_response.body : nil
       when 'json'
         raise NotImplementedError, 'We do not handle JSON yet!'
-        result = ''
-        prove_json(result)
       when 'php'
         raise NotImplementedError, 'We do not handle PHP yet!'
-        result = ''
-        prove_php(result)
       when 'rss'
         raise NotImplementedError, 'We do not handle RSS yet!'
-        result = ''
-        prove_rss(result)
       end
 
       # TODO: make a fine grained distinction
       case http_response
       when Net::HTTPSuccess
-        return result.to_s
-      when Net::HTTPMovedPermanently,
-           Net::HTTPFound,
-           Net::HTTPSeeOther,
-           Net::HTTPTemporaryRedirect
-        raise ContentError.new("#{http_response}:\n\n#{result}")
+        return result
+
+      when Net::HTTPBadRequest,
+        Net::HTTPForbidden,
+        Net::HTTPServiceUnavailable
+        raise ExternalError.new("#{http_response}:\n\n#{result}")
       else
-        raise ContentError.new("#{http_response}:\n\n#{result}")
+        raise ExternalError.new("#{http_response}:\n\n#{result}")
       end
 
     # are all external errors caught here?
@@ -71,67 +63,76 @@ module YANAPI
     rescue Nokogiri::XML::SyntaxError => e
       raise ContentError.new(e)
     end # get
-    
+
+    #########
     protected
+    # It checks params and returns a validated params hash.
+    def check_params(params)
+      # It requires <:appid> to be present.
+      unless params.has_key?(:appid)
+        fail UserError, 'APPID is missing!'
+      end
+
+      # It accepts only valid output formats.
+      unless VALID_OUTPUT_FORMATS.include?(params[:output])
+        fail UserError, "The output type <#{params[:output]}> is not supported!"
+      end
+
+      # It rejects <:callback> for all output formats but <json>.
+      if params[:output] != 'json' && params[:callback]
+        fail UserError,
+        "Output type #{params[:output]} is incompatible with <:callback>!"
+      end
+
+      # It accepts only unique values for every parameter,
+      # they can be Strings or Numbers.
+      # We do not support multiple values for categories and regions yet.
+      # Multiple values will be provided as Arrays:
+      # :category_id => [123, 456, 789].
+      params.each_pair do |k, v|
+        unless (v.instance_of?(String) || v.instance_of?(Fixnum))
+          fail UserError, "The value <:#{k}> is not unique!"
+        end
+      end
+
+      params
+    end # check_params
     
-    # Returns an URI::HTTP object containing the complete url for the request.
+    # It returns an URI::HTTP object containing the complete url for the request.
     def build_url(params)
-      search_method = params[:method]
-      params.delete(:method)
-      
-      base_url = [HOST, SERVICE, SERVICE_VERSION, search_method].join('/')
-      
-      params = expand_params(params)      
-      reserved_chars = Regexp.new(/[!*'();:@&=+$,\/?#\]\[]/)
-      # Every string is escaped twice.
-      # First time to allow only ascii characters.
-      # Second time to escape all url reserved chars.
+      # URI does not know if our string contains special characters or not.
+      # That's why it treats them as special, we need a stricter form and
+      # provide a list of characters which should be escaped.
+      reserved_chars = Regexp.new(/[ !*'();:@&=+$,\/?#\]\[]/)
+
+
+      expanded_params = expand_params(params) # It is an array now! 
       escaped_params = params.collect do |k, v|
-        k = URI.escape((URI.escape(k.to_s)), unsafe = reserved_chars)
-        v = URI.escape((URI.escape(v.to_s)), usafe = reserved_chars)
+        k = URI.escape(k.to_s, unsafe = reserved_chars)
+        v = URI.escape(v.to_s, unsafe = reserved_chars)
         "#{k}=#{v}"
       end
       
       query = escaped_params.join('&')
-      if $DEBUG
-        $stderr.print 'Joined query parameters: '
-        $stderr.puts query
-      end
+      base_url = [HOST, SERVICE, SERVICE_VERSION, @method].join('/')
+      url = base_url + '?' + query
       
-      url = URI.parse(base_url + '?' + query)
-
-      return url
+      URI.parse(url)
     end # build_url
-    
-    # Check params, my sheet
-    #--
-    # validates presense of :method
-    # validates type of :method
-    # validates presense of :appid
-    # validates uniqueness of all params
-    # (category_name|category_id may or region be repeated)
-    # default values will be propagated, not deleted (defaults can change)
-    def check_params(params)
-      unless params.include?(:appid)
-        raise Error, 'APPID is missing!'
-      end
-      unless params.include?(:method)
-        raise Error, 'Search Method is missing!'
-      end
-
-      allowed_methods = %w(questionSearch getByUser getByCategory getQuestion)
-      unless allowed_methods.include?(params[:method])
-        raise Error, "The search method #{params[:method]} is not supported!"
-      end
 
-      allowed_output = [nil, 'xml', 'json', 'rss', 'php']
-      unless allowed_output.include?(params[:output])
-        raise Error, "The output type #{params[:output]} is not supported!"
-      end
-
-      if params[:output] != 'json' && params[:callback]
-        raise Error, "You may not use callback with output type: #{@output}!"
+    # It expands multiple values to key-val pairs and returns a params array.
+    def expand_params(params)
+      expanded_params = []
+      
+      params.each_pair do |k, v|
+        if v.instance_of?(Array)
+          v.each { |val| expanded_params << [k, val] }
+        else
+          expanded_params << [k, v]
+        end
       end
+      
+      expanded_params.sort_by { |k, v| [k.to_s, v.to_s] }
     end
 
     # proves the presense of an error
@@ -147,41 +148,13 @@ module YANAPI
       end
 
       question = xml.at_xpath('//xmlns:Question', xml.root.namespaces)
-      unless question
-        message = 'The server returned an empty Result Set.'
-        raise EmptyResponse.new(message)
-      end
-    end
-
-    #
-    def prove_json(json)
-      raise NotImplementedError, 'We do not handle JSON yet!'
-    end
 
-    #
-    def prove_php(php)
-      raise NotImplementedError, 'We do not handle PHP yet!'
-    end
-
-    #
-    def prove_rss(rss)
-      raise NotImplementedError, 'We do not handle RSS yet!'
-    end
-    
-    def expand_params(params)
-      expanded_params = []
-      
-      params.each do |k,v|
-        if v.respond_to? :each and not String === v then
-          v.each { |s| expanded_params << [k, s] }
-        else
-          expanded_params << [k, v]
-        end
+      if question
+        xml
+      else
+        nil
       end
-      
-      expanded_params.sort_by { |k,v| [k.to_s, v.to_s] }
-    end
-    
+    end    
   end # Query
   
 end # YANAPI