google-api-client 0.2.0 → 0.3.0

data/CHANGELOG

@@ -1,3 +1,13 @@
+== 0.3.0
+
+* updated to use v1 of the discovery API
+* updated to use httpadapter 1.0.0
+* added OAuth 2 support to the command line tool
+* renamed some switches in the command line tool
+* added additional configuration capabilities
+* fixed a few deprecation warnings from dependencies
+* added gemspec to source control
+
 == 0.2.0
 
 * updated to use v1 of the discovery API

data/README.md

@@ -0,0 +1,69 @@
+# APIClient
+
+<dl>
+  <dt>Homepage</dt><dd><a href="http://code.google.com/p/google-api-ruby-client">http://code.google.com/p/google-api-ruby-client</a></dd>
+  <dt>Author</dt><dd><a href="mailto:bobaman@google.com">Bob Aman</a></dd>
+  <dt>Copyright</dt><dd>Copyright © 2011 Google, Inc.</dd>
+  <dt>License</dt><dd>Apache 2.0</dd>
+</dl>
+
+# Description
+
+The Google API Ruby Client makes it trivial to discover and access supported
+APIs.
+
+# Example Usage
+
+    # Initialize the client
+    require 'google/api_client'
+    require 'signet/oauth_1/client'
+    client = Google::APIClient.new(
+      :service => 'buzz',
+      # Buzz has API-specific endpoints
+      :authorization => Signet::OAuth1::Client.new(
+        :temporary_credential_uri =>
+          'https://www.google.com/accounts/OAuthGetRequestToken',
+        :authorization_uri =>
+          'https://www.google.com/buzz/api/auth/OAuthAuthorizeToken',
+        :token_credential_uri =>
+          'https://www.google.com/accounts/OAuthGetAccessToken',
+        :client_credential_key => 'anonymous',
+        :client_credential_secret => 'anonymous'
+      )
+    )
+    client.authorization.fetch_temporary_credential!(
+      :additional_parameters => {
+        'scope' => 'https://www.googleapis.com/auth/buzz'
+      }
+    )
+    redirect_uri = client.authorization.authorization_uri(
+      :additional_parameters => {
+        'domain' => client.authorization.client_credential_key,
+        'scope' => 'https://www.googleapis.com/auth/buzz'
+      }
+    )
+    # Redirect user here
+    client.authorization.fetch_token_credential!(:verifier => '12345')
+    
+    # Discover available methods
+    method_names = client.discovered_api('buzz').to_h.keys
+    
+    # Make an API call
+    response = client.execute(
+      'chili.activities.list',
+      {'scope' => '@self', 'userId' => '@me', 'alt' => 'json'}
+    )
+    status, headers, body = response
+
+# Install
+
+Be sure `http://rubygems.org/` is in your gem sources.
+
+For normal client usage, this is sufficient:
+
+    $ sudo gem install google-api-client
+
+The command line interface, the example applications, and the test suite
+require additional dependencies. These may be obtained with:
+
+    $ sudo gem install google-api-client --development --force --no-rdoc --no-ri

data/Rakefile

@@ -4,11 +4,8 @@ $LOAD_PATH.uniq!
 
 require 'rubygems'
 require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
-require 'rake/packagetask'
-require 'rake/gempackagetask'
 
+gem 'rspec', '~> 1.2.9'
 begin
   require 'spec/rake/spectask'
 rescue LoadError
@@ -27,6 +24,8 @@ PKG_HOMEPAGE       = 'http://code.google.com/p/google-api-ruby-client/'
 
 RELEASE_NAME       = "REL #{PKG_VERSION}"
 
+PKG_AUTHOR         = "Bob Aman"
+PKG_AUTHOR_EMAIL   = "bobaman@google.com"
 PKG_SUMMARY        = 'Package Summary'
 PKG_DESCRIPTION    = <<-TEXT
 The Google API Ruby Client makes it trivial to discover and access supported

data/bin/google-api

@@ -108,8 +108,8 @@ HTML
             options[:api] = s
           end
           opts.on(
-              "--service-version <id>", String,
-              "Select service version") do |id|
+              "--api-version <id>", String,
+              "Select api version") do |id|
             options[:version] = id
           end
           opts.on(
@@ -165,7 +165,7 @@ HTML
             "\nAvailable commands:\n" +
             "    oauth-1-login   Log a user into an API with OAuth 1.0a\n" +
             "    oauth-2-login   Log a user into an API with OAuth 2.0 d10\n" +
-            "    list            List the methods available for a service\n" +
+            "    list            List the methods available for an API\n" +
             "    execute         Execute a method on the API\n" +
             "    irb             Start an interactive client session"
           )
@@ -238,17 +238,27 @@ HTML
         end
 
         if options[:discovery_uri]
-          client.discovery_uri = options[:discovery_uri]
+          if options[:api] && options[:version]
+            client.register_discovery_uri(
+              options[:api], options[:version], options[:discovery_uri]
+            )
+          else
+            STDERR.puts(
+              'Cannot register a discovery URI without ' +
+              'specifying an API and version.'
+            )
+            exit(1)
+          end
         end
 
         return client
       end
 
-      def api_version(api, version)
+      def api_version(api_name, version)
         v = version
         if !version
-          if client.preferred_version(api)
-            v = client.preferred_version(api).version
+          if client.preferred_version(api_name)
+            v = client.preferred_version(api_name).version
           else
             v = 'v1'
           end
@@ -284,13 +294,12 @@ HTML
           exit(0)
         else
           $verifier = nil
-          # TODO(bobaman): Cross-platform?
-          logger = WEBrick::Log.new('/dev/null')
           server = WEBrick::HTTPServer.new(
             :Port => OAUTH_SERVER_PORT,
-            :Logger => logger,
-            :AccessLog => logger
+            :Logger => WEBrick::Log.new,
+            :AccessLog => WEBrick::Log.new
           )
+          server.logger.level = 0
           trap("INT") { server.shutdown }
 
           server.mount("/", OAuthVerifierServlet)
@@ -379,7 +388,7 @@ HTML
           )
 
           # Launch browser
-          Launchy::Browser.run(oauth_client.authorization_uri.to_s)
+          Launchy.open(oauth_client.authorization_uri.to_s)
 
           server.start
           oauth_client.code = $verifier
@@ -399,18 +408,28 @@ HTML
       end
 
       def list
-        api = options[:api]
-        unless api
+        api_name = options[:api]
+        unless api_name
           STDERR.puts('No API name supplied.')
           exit(1)
         end
         client = Google::APIClient.new(:authorization => nil)
         if options[:discovery_uri]
-          client.discovery_uri = options[:discovery_uri]
+          if options[:api] && options[:version]
+            client.register_discovery_uri(
+              options[:api], options[:version], options[:discovery_uri]
+            )
+          else
+            STDERR.puts(
+              'Cannot register a discovery URI without ' +
+              'specifying an API and version.'
+            )
+            exit(1)
+          end
         end
-        version = api_version(api, options[:version])
-        service = client.discovered_api(api, version)
-        rpcnames = service.to_h.keys
+        version = api_version(api_name, options[:version])
+        api = client.discovered_api(api_name, version)
+        rpcnames = api.to_h.keys
         puts rpcnames.sort.join("\n")
         exit(0)
       end
@@ -447,7 +466,7 @@ HTML
           method.upcase!
           request = [method, uri.to_str, headers, [request_body]]
           request = client.generate_authenticated_request(:request => request)
-          response = client.transmit_request(request)
+          response = client.transmit(request)
           status, headers, body = response
           puts body
           exit(0)
@@ -457,14 +476,14 @@ HTML
             STDERR.puts('No rpcname supplied.')
             exit(1)
           end
-          api = options[:api] || self.rpcname[/^([^\.]+)\./, 1]
-          version = api_version(api, options[:version])
-          service = client.discovered_api(api, version)
-          method = service.to_h[self.rpcname]
+          api_name = options[:api] || self.rpcname[/^([^\.]+)\./, 1]
+          version = api_version(api_name, options[:version])
+          api = client.discovered_api(api_name, version)
+          method = api.to_h[self.rpcname]
           if !method
             STDERR.puts(
               "Method #{self.rpcname} does not exist for " +
-              "#{api}-#{version}."
+              "#{api_name}-#{version}."
             )
             exit(1)
           end
@@ -477,10 +496,13 @@ HTML
             parameters['xoauth_requestor_id'] = options[:requestor_id]
           end
           begin
-            response = client.execute(
-              method, parameters, request_body, headers
+            result = client.execute(
+              :api_method => method,
+              :parameters => parameters,
+              :merged_body => request_body,
+              :headers => headers
             )
-            status, headers, body = response
+            status, headers, body = result.response
             puts body
             exit(0)
           rescue ArgumentError => e

data/lib/google/api_client.rb

@@ -17,9 +17,12 @@ require 'httpadapter'
 require 'json'
 require 'stringio'
 
+require 'google/api_client/version'
 require 'google/api_client/errors'
 require 'google/api_client/environment'
 require 'google/api_client/discovery'
+require 'google/api_client/reference'
+require 'google/api_client/result'
 
 module Google
   # TODO(bobaman): Document all this stuff.
@@ -65,19 +68,11 @@ module Google
         'google-api-ruby-client/' + VERSION::STRING +
         ' ' + ENV::OS_VERSION
       ).strip
-      # This is mostly a default for the sake of convenience.
-      # Unlike most other options, this one may be nil, so we check for
-      # the presence of the key rather than checking the value.
-      if options.has_key?("parser")
-        self.parser = options["parser"]
-      else
-        require 'google/api_client/parsers/json_parser'
-        # NOTE: Do not rely on this default value, as it may change
-        self.parser = Google::APIClient::JSONParser
-      end
       # The writer method understands a few Symbols and will generate useful
       # default authentication mechanisms.
       self.authorization = options["authorization"] || :oauth_2
+      self.key = options["key"]
+      self.user_ip = options["user_ip"]
       # The HTTP adapter controls all of the HTTP traffic the client generates.
       # By default, Net::HTTP is used, but adding support for other clients
       # is trivial.
@@ -94,33 +89,6 @@ module Google
       return self
     end
 
-
-    ##
-    # Returns the parser used by the client.
-    #
-    # @return [#serialize, #parse]
-    #   The parser used by the client.  Any object that implements both a
-    #   <code>#serialize</code> and a <code>#parse</code> method may be used.
-    #   If <code>nil</code>, no parsing will be done.
-    attr_reader :parser
-
-    ##
-    # Sets the parser used by the client.
-    #
-    # @param [#serialize, #parse] new_parser
-    #   The parser used by the client.  Any object that implements both a
-    #   <code>#serialize</code> and a <code>#parse</code> method may be used.
-    #   If <code>nil</code>, no parsing will be done.
-    def parser=(new_parser)
-      if new_parser &&
-          !new_parser.respond_to?(:serialize) &&
-          !new_parser.respond_to?(:parse)
-        raise TypeError,
-          'Expected parser object to respond to #serialize and #parse.'
-      end
-      @parser = new_parser
-    end
-
     ##
     # Returns the authorization mechanism used by the client.
     #
@@ -177,6 +145,18 @@ module Google
       return @authorization
     end
 
+    ##
+    # The application's API key issued by the API console.
+    #
+    # @return [String] The API key..
+    attr_accessor :key
+
+    ##
+    # The IP address of the user this request is being performed on behalf of.
+    #
+    # @return [String] The user's IP address.
+    attr_accessor :user_ip
+
     ##
     # Returns the HTTP adapter used by the client.
     #
@@ -280,7 +260,7 @@ module Google
           "Expected String or StringIO, got #{discovery_document.class}."
       end
       @discovery_documents["#{api}:#{version}"] =
-        JSON.parse(discovery_document)
+        ::JSON.parse(discovery_document)
     end
 
     ##
@@ -289,18 +269,30 @@ module Google
     # @return [Hash] The parsed JSON from the directory document.
     def directory_document
       return @directory_document ||= (begin
-        request_uri = self.directory_uri
-        request = ['GET', request_uri, [], []]
-        response = self.transmit_request(request)
+        request = self.generate_request(
+          :http_method => 'GET',
+          :uri => self.directory_uri,
+          :authenticated => false
+        )
+        response = self.transmit(request)
         status, headers, body = response
-        if status == 200 # TODO(bobaman) Better status code handling?
-          merged_body = StringIO.new
-          body.each do |chunk|
-            merged_body.write(chunk)
+        if status >= 200 && status < 300
+          # TODO(bobaman) Better status code handling?
+          merged_body = body.inject(StringIO.new) do |accu, chunk|
+            accu.write(chunk)
+            accu
           end
-          merged_body.rewind
-          JSON.parse(merged_body.string)
-        else
+          ::JSON.parse(merged_body.string)
+        elsif status >= 400 && status < 500
+          _, request_uri, _, _ = request
+          raise ClientError,
+            "Could not retrieve discovery document at: #{request_uri}"
+        elsif status >= 500 && status < 600
+          _, request_uri, _, _ = request
+          raise ServerError,
+            "Could not retrieve discovery document at: #{request_uri}"
+        elsif status > 600
+          _, request_uri, _, _ = request
           raise TransmissionError,
             "Could not retrieve discovery document at: #{request_uri}"
         end
@@ -317,18 +309,30 @@ module Google
       api = api.to_s
       version = version || 'v1'
       return @discovery_documents["#{api}:#{version}"] ||= (begin
-        request_uri = self.discovery_uri(api, version)
-        request = ['GET', request_uri, [], []]
-        response = self.transmit_request(request)
+        request = self.generate_request(
+          :http_method => 'GET',
+          :uri => self.discovery_uri(api, version),
+          :authenticated => false
+        )
+        response = self.transmit(request)
         status, headers, body = response
-        if status == 200 # TODO(bobaman) Better status code handling?
-          merged_body = StringIO.new
-          body.each do |chunk|
-            merged_body.write(chunk)
+        if status >= 200 && status < 300
+          # TODO(bobaman) Better status code handling?
+          merged_body = body.inject(StringIO.new) do |accu, chunk|
+            accu.write(chunk)
+            accu
           end
-          merged_body.rewind
-          JSON.parse(merged_body.string)
-        else
+          ::JSON.parse(merged_body.string)
+        elsif status >= 400 && status < 500
+          _, request_uri, _, _ = request
+          raise ClientError,
+            "Could not retrieve discovery document at: #{request_uri}"
+        elsif status >= 500 && status < 600
+          _, request_uri, _, _ = request
+          raise ServerError,
+            "Could not retrieve discovery document at: #{request_uri}"
+        elsif status > 600
+          _, request_uri, _, _ = request
           raise TransmissionError,
             "Could not retrieve discovery document at: #{request_uri}"
         end
@@ -344,7 +348,7 @@ module Google
         document_base = self.directory_uri
         if self.directory_document && self.directory_document['items']
           self.directory_document['items'].map do |discovery_document|
-            ::Google::APIClient::API.new(
+            Google::APIClient::API.new(
               document_base,
               discovery_document
             )
@@ -373,7 +377,7 @@ module Google
         document_base = self.discovery_uri(api, version)
         discovery_document = self.discovery_document(api, version)
         if document_base && discovery_document
-          ::Google::APIClient::API.new(
+          Google::APIClient::API.new(
             document_base,
             discovery_document
           )
@@ -442,8 +446,6 @@ module Google
     #   - <code>:version</code> — 
     #     The service version.  Only used if <code>api_method</code> is a
     #     <code>String</code>.  Defaults to <code>'v1'</code>.
-    #   - <code>:parser</code> — 
-    #     The parser for the response.
     #   - <code>:authorization</code> — 
     #     The authorization mechanism for the response.  Used only if
     #     <code>:authenticated</code> is <code>true</code>.
@@ -457,17 +459,22 @@ module Google
     #
     # @example
     #   request = client.generate_request(
-    #     'chili.activities.list',
-    #     {'scope' => '@self', 'userId' => '@me', 'alt' => 'json'}
+    #     :api_method => 'chili.activities.list',
+    #     :parameters =>
+    #       {'scope' => '@self', 'userId' => '@me', 'alt' => 'json'}
     #   )
     #   method, uri, headers, body = request
-    def generate_request(
-        api_method, parameters={}, body='', headers=[], options={})
+    def generate_request(options={})
+      # Note: The merge method on a Hash object will coerce an API Reference
+      # object into a Hash and merge with the default options.
       options={
-        :parser => self.parser,
         :version => 'v1',
-        :authorization => self.authorization
+        :authorization => self.authorization,
+        :key => self.key,
+        :user_ip => self.user_ip
       }.merge(options)
+      # The Reference object is going to need this to do method ID lookups.
+      options[:client] = self
       # The default value for the :authenticated option depends on whether an
       # authorization mechanism has been set.
       if options[:authorization]
@@ -475,27 +482,8 @@ module Google
       else
         options = {:authenticated => false}.merge(options)
       end
-      if api_method.kind_of?(String) || api_method.kind_of?(Symbol)
-        api_method = api_method.to_s
-        # This method of guessing the API is unreliable. This will fail for
-        # APIs where the first segment of the RPC name does not match the
-        # service name. However, this is a fallback mechanism anyway.
-        # Developers should be passing in a reference to the method, rather
-        # than passing in a string or symbol. This should raise an error
-        # in the case of a mismatch.
-        api = api_method[/^([^.]+)\./, 1]
-        api_method = self.discovered_method(
-          api_method, api, options[:version]
-        )
-      elsif !api_method.kind_of?(::Google::APIClient::Method)
-        raise TypeError,
-          "Expected String, Symbol, or Google::APIClient::Method, " +
-          "got #{api_method.class}."
-      end
-      unless api_method
-        raise ArgumentError, "API method could not be found."
-      end
-      request = api_method.generate_request(parameters, body, headers)
+      reference = Google::APIClient::Reference.new(options)
+      request = reference.to_request
       if options[:authenticated]
         request = self.generate_authenticated_request(:request => request)
       end
@@ -503,47 +491,13 @@ module Google
     end
 
     ##
-    # Generates a request and transmits it.
-    #
-    # @param [Google::APIClient::Method, String] api_method
-    #   The method object or the RPC name of the method being executed.
-    # @param [Hash, Array] parameters
-    #   The parameters to send to the method.
-    # @param [String] body The body of the request.
-    # @param [Hash, Array] headers The HTTP headers for the request.
-    # @param [Hash] options
-    #   The configuration parameters for the request.
-    #   - <code>:version</code> — 
-    #     The service version.  Only used if <code>api_method</code> is a
-    #     <code>String</code>.  Defaults to <code>'v1'</code>.
-    #   - <code>:adapter</code> — 
-    #     The HTTP adapter.
-    #   - <code>:parser</code> — 
-    #     The parser for the response.
-    #   - <code>:authorization</code> — 
-    #     The authorization mechanism for the response.  Used only if
-    #     <code>:authenticated</code> is <code>true</code>.
-    #   - <code>:authenticated</code> — 
-    #     <code>true</code> if the request must be signed or otherwise
-    #     authenticated, <code>false</code>
-    #     otherwise.  Defaults to <code>true</code>.
+    # Signs a request using the current authorization mechanism.
     #
-    # @return [Array] The response from the API.
+    # @param [Hash] options The options to pass through.
     #
-    # @example
-    #   response = client.execute(
-    #     'chili.activities.list',
-    #     {'scope' => '@self', 'userId' => '@me', 'alt' => 'json'}
-    #   )
-    #   status, headers, body = response
-    def execute(api_method, parameters={}, body='', headers=[], options={})
-      request = self.generate_request(
-        api_method, parameters, body, headers, options
-      )
-      return self.transmit_request(
-        request,
-        options[:adapter] || self.http_adapter
-      )
+    # @return [Array] The signed or otherwise authenticated request.
+    def generate_authenticated_request(options={})
+      return authorization.generate_authenticated_request(options)
     end
 
     ##
@@ -553,7 +507,7 @@ module Google
     # @param [#transmit] adapter The HTTP adapter.
     #
     # @return [Array] The response from the server.
-    def transmit_request(request, adapter=self.http_adapter)
+    def transmit(request, adapter=self.http_adapter)
       if self.user_agent != nil
         # If there's no User-Agent header, set one.
         method, uri, headers, body = request
@@ -577,13 +531,89 @@ module Google
     end
 
     ##
-    # Signs a request using the current authorization mechanism.
+    # Executes a request, wrapping it in a Result object.
     #
-    # @param [Hash] options The options to pass through.
+    # @param [Google::APIClient::Method, String] api_method
+    #   The method object or the RPC name of the method being executed.
+    # @param [Hash, Array] parameters
+    #   The parameters to send to the method.
+    # @param [String] body The body of the request.
+    # @param [Hash, Array] headers The HTTP headers for the request.
+    # @param [Hash] options
+    #   The configuration parameters for the request.
+    #   - <code>:version</code> — 
+    #     The service version.  Only used if <code>api_method</code> is a
+    #     <code>String</code>.  Defaults to <code>'v1'</code>.
+    #   - <code>:adapter</code> — 
+    #     The HTTP adapter.
+    #   - <code>:authorization</code> — 
+    #     The authorization mechanism for the response.  Used only if
+    #     <code>:authenticated</code> is <code>true</code>.
+    #   - <code>:authenticated</code> — 
+    #     <code>true</code> if the request must be signed or otherwise
+    #     authenticated, <code>false</code>
+    #     otherwise.  Defaults to <code>true</code>.
     #
-    # @return [Array] The signed or otherwise authenticated request.
-    def generate_authenticated_request(options={})
-      return authorization.generate_authenticated_request(options)
+    # @return [Array] The response from the API.
+    #
+    # @example
+    #   request = client.generate_request(
+    #     :api_method => 'chili.activities.list',
+    #     :parameters =>
+    #       {'scope' => '@self', 'userId' => '@me', 'alt' => 'json'}
+    #   )
+    def execute(*params)
+      # This block of code allows us to accept multiple parameter passing
+      # styles, and maintaining some backwards compatibility.
+      #
+      # Note: I'm extremely tempted to deprecate this style of execute call.
+      if params.last.respond_to?(:to_hash) && params.size == 1
+        options = params.pop
+      else
+        options = {}
+      end
+      options[:api_method] = params.shift if params.size > 0
+      options[:parameters] = params.shift if params.size > 0
+      options[:merged_body] = params.shift if params.size > 0
+      options[:headers] = params.shift if params.size > 0
+      options[:client] = self
+
+      reference = Google::APIClient::Reference.new(options)
+      request = self.generate_request(reference)
+      response = self.transmit(
+        request,
+        options[:adapter] || self.http_adapter
+      )
+      return Google::APIClient::Result.new(reference, request, response)
+    end
+
+    ##
+    # Same as Google::APIClient#execute, but raises an exception if there was
+    # an error.
+    #
+    # @see Google::APIClient#execute
+    def execute!(*params)
+      result = self.execute(*params)
+      status, _, _ = result.response
+      if result.data.respond_to?(:error) &&
+          result.data.error.respond_to?(:message)
+        # You're going to get a terrible error message if the response isn't
+        # parsed successfully as an error.
+        error_message = result.data.error.message
+      elsif result.data['error'] && result.data['error']['message']
+        error_message = result.data['error']['message']
+      end
+      if status >= 400 && status < 500
+        raise ClientError,
+          error_message || "A client error has occurred."
+      elsif status >= 500 && status < 600
+        raise ServerError,
+          error_message || "A server error has occurred."
+      elsif status > 600
+        raise TransmissionError,
+          error_message || "A transmission error has occurred."
+      end
+      return result
     end
   end
 end