eventfulapi 2.1.1 → 2.2.0

data/README

@@ -5,6 +5,5 @@ calendars, and users.
 See http://api.eventful.com/ for general information about the API, and
 http://api.eventful.com/docs/libs/ruby/doc for documentation about the Ruby library.
 
-Copyright 2005-2007 EVDB, Inc. All rights reserved. This module is distributed
-under the same terms as Ruby itself (see
-http://www.ruby-lang.org/en/LICENSE.txt)
+Copyright 2005-2007 EVDB, Inc. This module is distributed under the same terms 
+as Ruby itself (see http://www.ruby-lang.org/en/LICENSE.txt)

data/lib/eventful/api.rb

@@ -13,36 +13,89 @@
 #  begin
 #
 #    # Start an API session with a username and password
-#    eventful = Eventful::API.new 'application_key', 
-#                                 'user' => 'username',
-#                                 'password' => 'password'
+#    eventful = Eventful::API.new 'application_key',
+#                                 :user => 'username',
+#                                 :password => 'password'
 #
 #    # Lookup an event by its unique id
 #    event = eventful.call 'events/get',
-#                          'id' => 'E0-001-001042544-7'
+#                          :id => 'E0-001-001042544-7'
 #
 #    puts "Event Title: #{event['title']}"
-#    
+#
 #    # Get information about that event's venue
-#    venue = eventful.call 'venues/get', 
-#                          'id' => event['venue_id']
+#    venue = eventful.call 'venues/get',
+#                          :id => event['venue_id']
 #
 #    puts "Venue: #{venue['name']}"
 #
 #  rescue Eventful::APIError => e
-#    puts "There was an error fetching the event: #{e}"
+#    puts "There was a problem with the API: #{e}"
+#  end
+#
+#
+# == Another Example
+#
+#  require 'rubygems'
+#  require 'eventful/api'
+#
+#  # First, create our Eventful::API object
+#  eventful = Eventful::API.new 'application_key'
+#
+#  loop do
+#    # Ask the user what and where to search
+#    puts "Search where? (Ex: San Diego)"
+#    print "? "
+#    location = gets.chomp
+#    puts "Search for what (Ex: music)"
+#    print "? "
+#    query = gets.chomp
+#
+#    # This is the cool part!
+#    results = eventful.call 'events/search',
+#                            :keywords => query,
+#                            :location => location,
+#                            :page_size => 5
+#
+#    # If we couldn't find anything, ask the user again
+#    if results['events'].nil? then
+#      puts
+#      puts "Hmm. I couldn't find anything. Sorry."
+#      puts
+#      next
+#    end
+#
+#    # Output the results
+#    results['events']['event'].each do |event|
+#      puts
+#      puts "http://eventful.com/events/" + event['id']
+#      puts event['title']
+#      puts "  at " + event['venue_name']
+#      puts "  on " + Time.parse(event['start_time']).strftime("%a, %b %d, %I:%M %p") if event['start_time']
+#    end
+#    puts
 #  end
 #
 #
 # == API Key
 #
-# Use of the Eventful API requires an application key 
+# Use of the Eventful API requires an application key
 # (see http://api.eventful.com/keys for more information).
 #
 # == Change Notes
 #
 # === Eventful API
 #
+# ==== Version 2.2.0
+#
+# - The authentication bug has been fixed, so I'm rolling back the workaround.
+# - Documented the parameters for specifying alternative API servers when calling
+#   Eventful.new
+# - The names of these keys have been changed to be a bit friendlier. The old
+#   keys will still work fine.
+# - Hash keys to methods can now be Symbols, in addition to strings
+# - A fun new example, just because
+#
 # ==== Version 2.1.1
 #
 # - Includes a workaround fix for an authentication bug. This fix may be rolled
@@ -50,10 +103,10 @@
 #
 # ==== Version 2.1
 #
-# - As EVDB Inc. has been renamed Eventful Inc., the EVDB module has been 
-#   renamed Eventful, and the gem is now named eventfulapi. Support for the 
+# - As EVDB Inc. has been renamed Eventful Inc., the EVDB module has been
+#   renamed Eventful, and the gem is now named eventfulapi. Support for the
 #   evdbapi gem is being discontinued; please use the eventfulapi gem from now on.
-# - Much better at throwing an error when a network or server problem happens, 
+# - Much better at throwing an error when a network or server problem happens,
 #   rather than failing silently and mysteriously
 # - Documentation improvements
 #
@@ -63,7 +116,7 @@
 #
 # - Fixed a minor documentation error
 #
-# ==== Version 2.0 
+# ==== Version 2.0
 #
 # Version 2.0 of this library includes some significant changes which may not
 # be backwards compatible. Specifically:
@@ -78,9 +131,9 @@
 # == Information
 #
 # Status::             Stable
-# Version::            2.1.1
+# Version::            2.2.0
 # Date::               2007-03-24
-# Current Author::     Paul Knight (mailto:pknight@eventful.com)
+# Current Author::     Paul Knight (mailto:paul@eventful.com)
 # Previous Authors::   Joe Auricchio
 # Copyright::          Copyright (C) 2005-2007 Eventful Inc.
 # License::            This code is distributed under the same terms as Ruby itself (see http://www.ruby-lang.org/en/LICENSE.txt)
@@ -104,8 +157,7 @@ require 'cgi'
 require 'net/http'
 require 'base64'
 require 'digest/md5'
-require 'open-uri'
-require 'rexml/document'
+
 
 
 
@@ -113,97 +165,140 @@ require 'rexml/document'
 module Eventful
 
 
-  
+
   # Version descriptor of this library
-  VERSION = '2.1'
-  
+  VERSION = '2.2.0'
+
   # Default API server to connect to
-  DEFAULT_API_SERVER = 'api.eventful.com' #:nodoc:
+  DEFAULT_SERVER = 'api.eventful.com' #:nodoc:
   # Default server port
-  DEFAULT_API_PORT = 80 #:nodoc:
+  DEFAULT_PORT = 80 #:nodoc:
   # Default server path
-  DEFAULT_API_ROOT = '/yaml/' #:nodoc:
-  
+  DEFAULT_ROOT = '/yaml/' #:nodoc:
+
   # Our POST data boundary
   BOUNDARY = '1E666D29B5E749F6A145BE8A576049E6' #:nodoc:
   BOUNDARY_MARKER = "--#{BOUNDARY}" #:nodoc:
   BOUNDARY_END_MARKER = "--#{BOUNDARY}--" #:nodoc:
-  
-  
-  
+
+
+
   # Parent Error used for all Eventful exceptions
   class Error < StandardError ; end
-  
+
   # An error that may also include the YAML response from the server
   class APIError < Error
     attr_reader :response
-    
+
     # Creates a new exception.
     def initialize(response)
       super
       @response = response
     end
-    
+
     # The error string returned by the API call.
     def to_s
       "#{@response['string']}: #{@response['description']}"
     end
   end
-  
-  
-  
+
+
+
   # A class for working with the Eventful API.
   class API
-    
-    
-    
+
+
+
     # Create an object for working with the Eventful API. Working with the API
     # requires an application key, which can be obtained at http://api.eventful.com/keys/
     #
     # Options may be:
     #
-    # <tt>'user'</tt>:: Authenticate as this user, required for some API methods. A password must also be specified.
-    # <tt>'password'</tt>:: Password for user authentication.
+    # <tt>:user</tt>:: Authenticate as this user, required for some API methods. A password must also be specified.
+    # <tt>:password</tt>:: Password for user authentication.
+    #
+    # If both <tt>user</tt> and <tt>password</tt> are specified, then digest
+    # authenticatino will be used. Otherise, basic authentication will be used.
+    # Please note that basic authentication sends passwords in the clear.
+    # For more information, please see http://api.eventful.com/docs/auth
+    #
+    # ==== Testing Against Another Server
+    #
+    # For testing, you may use the following options for specifying a
+    # different API server:
+    #
+    # <tt>:server</tt>:: Hostname of the API server, default <tt>api.eventful.com</tt>
+    # <tt>:root</tt>:: Path to the root of all method calls, default <tt>/yaml/</tt>
+    # <tt>:port</tt>:: Server port, default <tt>80</tt>
+    #
+    # If the server is behind HTTP authentication, you can use:
+    #
+    # <tt>:http_user</tt>:: Username for HTTP authentication
+    # <tt>:http_password</tt>:: Password for HTTP authenciation
+    #
+    # Please note that none of these five options are needed for using the Eventful API.
+    #
+    # ==== Example
     #
-    # Example:
-    # 
     #  eventful = Eventful::API.new 'app_key',
-    #                               'user' => 'username', 
-    #                               'password' => 'password'
+    #                               :user => 'username',
+    #                               :password => 'password'
     #
     def initialize(app_key, options = {})
-      @api_server = options['api_server'] || DEFAULT_API_SERVER
-      @api_root = options['api_root'] || DEFAULT_API_ROOT
-      @api_port = options['api_port'] || DEFAULT_API_PORT
-      
-      @auth_user = options['auth_user']
-      @auth_password = options['auth_password']
-      
-      @authentication = nil
-      
+      # Grab our arguments
+
+      @server = find_option [:server, :api_server], options, DEFAULT_SERVER
+      @root = find_option [:root, :api_root], options, DEFAULT_ROOT
+      @port = find_option [:port, :api_port], options, DEFAULT_PORT
+
+      @http_user = find_option [:http_user, :auth_user], options
+      @http_password = find_option [:http_password, :auth_password], options
+
+      user = find_option [:user], options
+      password = find_option [:password], options
+
       # User authentication
-      if (options['user'] && options['password'])
-        nonce = get_nonce app_key
-        
+      if user and password
+        # Get a nonce; we expect an error response here, so rescue the exception and continue
+        begin
+          response = call 'users/login',
+                          :app_key => app_key
+        rescue APIError => error
+          raise unless error.response['nonce']
+          nonce = error.response['nonce']
+        end
+
         # Login with a hash of the nonce and our password
-        login_hash = Digest::MD5.hexdigest("#{nonce}:#{Digest::MD5.hexdigest(options['password'])}")
-        response = call 'users/login', 
-                        'app_key' => app_key, 
-                        'user' => options['user'], 
-                        'nonce' => nonce, 
-                        'response' => login_hash
-      
+        login_hash = Digest::MD5.hexdigest "#{nonce}:#{Digest::MD5.hexdigest(password)}"
+        response = call 'users/login',
+                        :app_key => app_key,
+                        :user => user,
+                        :nonce => nonce,
+                        :response => login_hash
+
         # Store authentication information and use it for all future calls
-        @authentication = { 'app_key' => app_key, 
-                            'user' => options['user'], 
-                            'user_key' => response['user_key'] }
+        @authentication = { :app_key => app_key,
+                            :user => user,
+                            :user_key => response['user_key'] }
       else
-        @authentication = { 'app_key' => app_key }
+        @authentication = { :app_key => app_key }
+      end
+    end
+
+
+
+    # Search through a method argument Hash for specified named parameters
+    def find_option(names, arguments, default = nil) #:nodoc:
+      result = default
+      names.each do |name|
+        result = arguments[name] || arguments[name.to_s] || result
       end
+      return result
     end
 
 
-    
+
+
     # Prepares the body of the POST request
     def prepare_post(params) #:nodoc:
       content = ""
@@ -215,7 +310,7 @@ module Eventful
           content += "Content-Transfer-Encoding: binary\r\n\r\n"
           content += open(value) { |f| f.read } + "\r\n"
         else
-          content += "Content-Disposition: form-data; name=\"#{CGI::escape(key.to_s)}\";\r\n\r\n#{value}\r\n" 
+          content += "Content-Disposition: form-data; name=\"#{CGI::escape(key.to_s)}\";\r\n\r\n#{value}\r\n"
         end
       end
       content += BOUNDARY_END_MARKER
@@ -228,50 +323,42 @@ module Eventful
     # a hash. Please see the Eventful API documentation (http://api.eventful.com/docs)
     # for information about methods and their parameters.
     #
-    # Example:
+    # ==== Example
     #
     #  event = eventful.call 'events/get',
-    #                        'id' => 'E0-001-001042544-7'
+    #                        :id => 'E0-001-001042544-7'
     #
     def call(method, params = {})
       # Use available auth tokens
       params.merge! @authentication if @authentication
 
-      response = Net::HTTP.start(@api_server, @api_port) do |connection|
-        if @auth_user && @auth_password then
+      response = Net::HTTP.start(@server, @port) do |connection|
+        if @http_user and @http_password then
           connection.post(
-            "#{@api_root}#{method}", 
-            prepare_post(params), 
-            "Content-type" => "multipart/form-data; boundary=#{BOUNDARY} ", 
-            "Authorization" => Base64.encode64("#{@auth_user}:#{@auth_password}"))
+            "#{@root}#{method}",
+            prepare_post(params),
+            "Content-type" => "multipart/form-data; boundary=#{BOUNDARY} ",
+            "Authorization" => Base64.encode64("#{@http_user}:#{@http_password}"))
         else
           connection.post(
-            "#{@api_root}#{method}", 
-            prepare_post(params), 
+            "#{@root}#{method}",
+            prepare_post(params),
             "Content-type" => "multipart/form-data; boundary=#{BOUNDARY} ")
         end
       end
-      
+
       # Raise an exception if we didn't get a 2xx response code
       response.value
-      
+
       yaml = YAML::load response.body
-      
+
       # Raise an error if we got an API error
       raise APIError.new(yaml['error']) if yaml['error']
 
       return yaml
     end
-    
-    # Only intended for the first users/login authentication call
-    def get_nonce(app_key) # :nodoc:
-      open "http://#{@api_server}/rest/users/login?app_key=#{CGI::escape app_key}" do |f|
-        (REXML::Document.new f.read).elements["error/nonce"].text
-      end
-    end
-    
-    
-    
+
+
+
   end # class API
 end # module Eventful
-

metadata

@@ -3,13 +3,13 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: eventfulapi
 version: !ruby/object:Gem::Version 
-  version: 2.1.1
-date: 2007-04-24 00:00:00 -07:00
+  version: 2.2.0
+date: 2007-05-14 00:00:00 -07:00
 summary: Interface to the Eventful API. http://eventful.com
 require_paths: 
 - lib
-email: pknight@eventful.com
-homepage: http://api.evdb.com
+email: paul@eventful.com
+homepage: http://api.eventful.com
 rubyforge_project: 
 description: 
 autorequire: eventful/api