google-api-client 0.1.3 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,11 @@
+== 0.2.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
+
 == 0.1.3
 
 * added support for manual overrides of the discovery URI

data/README

@@ -44,7 +44,7 @@ APIs.
   client.authorization.fetch_token_credential!(:verifier => '12345')
 
   # Discover available methods
-  method_names = client.discovered_service('buzz').to_h.keys
+  method_names = client.discovered_api('buzz').to_h.keys
 
   # Make an API call
   response = client.execute(

data/bin/google-api

@@ -26,7 +26,8 @@ module Google
 
         def do_GET(request, response)
           $verifier ||= Addressable::URI.unencode_component(
-            request.request_uri.to_s[/\?.*oauth_verifier=([^&$]+)(&|$)/, 1]
+            request.request_uri.to_s[/\?.*oauth_verifier=([^&$]+)(&|$)/, 1] ||
+            request.request_uri.to_s[/\?.*code=([^&$]+)(&|$)/, 1]
           )
           response.status = WEBrick::HTTPStatus::RC_ACCEPTED
           # This javascript will auto-close the tab after the
@@ -92,24 +93,24 @@ HTML
             options[:scope] = s
           end
           opts.on(
-              "--client-key <key>", String,
-                "Set the 2-legged OAuth key") do |k|
+              "--client-id <key>", String,
+                "Set the OAuth client id or key") do |k|
             options[:client_credential_key] = k
           end
           opts.on(
               "--client-secret <secret>", String,
-                "Set the 2-legged OAuth secret") do |s|
+                "Set the OAuth client secret") do |s|
             options[:client_credential_secret] = s
           end
           opts.on(
-              "-s", "--service <name>", String,
-              "Perform discovery on service") do |s|
-            options[:service_name] = s
+              "--api <name>", String,
+              "Perform discovery on API") do |s|
+            options[:api] = s
           end
           opts.on(
               "--service-version <id>", String,
               "Select service version") do |id|
-            options[:service_version] = id
+            options[:version] = id
           end
           opts.on(
               "--content-type <format>", String,
@@ -162,10 +163,11 @@ HTML
 
           opts.separator(
             "\nAvailable commands:\n" +
-            "    oauth-login   Log a user into an API\n" +
-            "    list          List the methods available for a service\n" +
-            "    execute       Execute a method on the API\n" +
-            "    irb           Start an interactive client session"
+            "    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" +
+            "    execute         Execute a method on the API\n" +
+            "    irb             Start an interactive client session"
           )
         end
       end
@@ -180,23 +182,98 @@ HTML
         self.send(symbol)
       end
 
+      def client
+        require 'signet/oauth_1/client'
+        require 'yaml'
+        require 'irb'
+        config_file = File.expand_path('~/.google-api.yaml')
+        authorization = nil
+        if File.exist?(config_file)
+          config = open(config_file, 'r') { |file| YAML.load(file.read) }
+        else
+          config = {}
+        end
+        if config["mechanism"]
+          authorization = config["mechanism"].to_sym
+        end
+
+        client = Google::APIClient.new(:authorization => authorization)
+
+        case authorization
+        when :oauth_1
+          if client.authorization &&
+              !client.authorization.kind_of?(Signet::OAuth1::Client)
+            STDERR.puts(
+              "Unexpected authorization mechanism: " +
+              "#{client.authorization.class}"
+            )
+            exit(1)
+          end
+          config = open(config_file, 'r') { |file| YAML.load(file.read) }
+          client.authorization.client_credential_key =
+            config["client_credential_key"]
+          client.authorization.client_credential_secret =
+            config["client_credential_secret"]
+          client.authorization.token_credential_key =
+            config["token_credential_key"]
+          client.authorization.token_credential_secret =
+            config["token_credential_secret"]
+        when :oauth_2
+          if client.authorization &&
+              !client.authorization.kind_of?(Signet::OAuth2::Client)
+            STDERR.puts(
+              "Unexpected authorization mechanism: " +
+              "#{client.authorization.class}"
+            )
+            exit(1)
+          end
+          config = open(config_file, 'r') { |file| YAML.load(file.read) }
+          client.authorization.scope = options[:scope]
+          client.authorization.client_id = config["client_id"]
+          client.authorization.client_secret = config["client_secret"]
+          client.authorization.access_token = config["access_token"]
+          client.authorization.refresh_token = config["refresh_token"]
+        else
+          # Dunno?
+        end
+
+        if options[:discovery_uri]
+          client.discovery_uri = options[:discovery_uri]
+        end
+
+        return client
+      end
+
+      def api_version(api, version)
+        v = version
+        if !version
+          if client.preferred_version(api)
+            v = client.preferred_version(api).version
+          else
+            v = 'v1'
+          end
+        end
+        return v
+      end
+
       COMMANDS = [
-        :oauth_login,
+        :oauth_1_login,
+        :oauth_2_login,
         :list,
         :execute,
         :irb,
         :fuzz
       ]
 
-      def oauth_login
+      def oauth_1_login
         require 'signet/oauth_1/client'
         require 'launchy'
         require 'yaml'
         if options[:client_credential_key] &&
             options[:client_credential_secret]
-          scope = options[:scope]
           config = {
-            "scope" => nil,
+            "mechanism" => "oauth_1",
+            "scope" => options[:scope],
             "client_credential_key" => options[:client_credential_key],
             "client_credential_secret" => options[:client_credential_secret],
             "token_credential_key" => nil,
@@ -229,19 +306,8 @@ HTML
             :client_credential_secret => 'anonymous',
             :callback => "http://localhost:#{OAUTH_SERVER_PORT}/"
           )
-          scope = options[:scope]
-          # Special cases
-          case scope
-          when "https://www.googleapis.com/auth/buzz",
-              "https://www.googleapis.com/auth/buzz.readonly"
-            oauth_client.authorization_uri =
-              'https://www.google.com/buzz/api/auth/OAuthAuthorizeToken?' +
-              "domain=#{oauth_client.client_credential_key}&" +
-              "scope=#{scope}&" +
-              "xoauth_displayname=Google%20API%20Client"
-          end
           oauth_client.fetch_temporary_credential!(:additional_parameters => {
-            :scope => scope,
+            :scope => options[:scope],
             :xoauth_displayname => 'Google API Client'
           })
 
@@ -251,7 +317,7 @@ HTML
           server.start
           oauth_client.fetch_token_credential!(:verifier => $verifier)
           config = {
-            "scope" => scope,
+            "scope" => options[:scope],
             "client_credential_key" =>
               oauth_client.client_credential_key,
             "client_credential_secret" =>
@@ -267,34 +333,90 @@ HTML
         end
       end
 
+      def oauth_2_login
+        require 'signet/oauth_2/client'
+        require 'launchy'
+        require 'yaml'
+        if !options[:client_credential_key] ||
+            !options[:client_credential_secret]
+          STDERR.puts('No client ID and secret supplied.')
+          exit(1)
+        end
+        if options[:access_token]
+          config = {
+            "mechanism" => "oauth_2",
+            "scope" => options[:scope],
+            "client_id" => options[:client_credential_key],
+            "client_secret" => options[:client_credential_secret],
+            "access_token" => options[:access_token],
+            "refresh_token" => options[:refresh_token]
+          }
+          config_file = File.expand_path('~/.google-api.yaml')
+          open(config_file, 'w') { |file| file.write(YAML.dump(config)) }
+          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
+          )
+          trap("INT") { server.shutdown }
+
+          server.mount("/", OAuthVerifierServlet)
+
+          oauth_client = Signet::OAuth2::Client.new(
+            :authorization_uri =>
+              'https://www.google.com/accounts/o8/oauth2/authorization',
+            :token_credential_uri =>
+              'https://www.google.com/accounts/o8/oauth2/token',
+            :client_id => options[:client_credential_key],
+            :client_secret => options[:client_credential_secret],
+            :redirect_uri => "http://localhost:#{OAUTH_SERVER_PORT}/",
+            :scope => options[:scope]
+          )
+
+          # Launch browser
+          Launchy::Browser.run(oauth_client.authorization_uri.to_s)
+
+          server.start
+          oauth_client.code = $verifier
+          oauth_client.fetch_access_token!
+          config = {
+            "mechanism" => "oauth_2",
+            "scope" => options[:scope],
+            "client_id" => oauth_client.client_id,
+            "client_secret" => oauth_client.client_secret,
+            "access_token" => oauth_client.access_token,
+            "refresh_token" => oauth_client.refresh_token
+          }
+          config_file = File.expand_path('~/.google-api.yaml')
+          open(config_file, 'w') { |file| file.write(YAML.dump(config)) }
+          exit(0)
+        end
+      end
+
       def list
-        service_name = options[:service_name]
-        unless service_name
-          STDERR.puts('No service name supplied.')
+        api = options[:api]
+        unless api
+          STDERR.puts('No API name supplied.')
           exit(1)
         end
-        client = Google::APIClient.new(
-          :service => service_name,
-          :authorization => nil
-        )
+        client = Google::APIClient.new(:authorization => nil)
         if options[:discovery_uri]
           client.discovery_uri = options[:discovery_uri]
         end
-        service_version =
-          options[:service_version] ||
-          client.latest_service_version(service_name).version
-        service = client.discovered_service(service_name, service_version)
+        version = api_version(api, options[:version])
+        service = client.discovered_api(api, version)
         rpcnames = service.to_h.keys
         puts rpcnames.sort.join("\n")
         exit(0)
       end
 
       def execute
-        require 'signet/oauth_1/client'
-        require 'yaml'
-        config_file = File.expand_path('~/.google-api.yaml')
-        signed = File.exist?(config_file)
-        authorization_type = :oauth_1
+        client = self.client
 
         # Setup HTTP request data
         request_body = ''
@@ -308,28 +430,6 @@ HTML
           headers << ['Content-Type', 'application/json']
         end
 
-        configure_authorization = lambda do |client|
-          if !client.authorization.kind_of?(Signet::OAuth1::Client)
-            STDERR.puts(
-              "Unexpected authorization mechanism: " +
-              "#{client.authorization.class}"
-            )
-            exit(1)
-          end
-          config = open(config_file, 'r') { |file| YAML.load(file.read) }
-          client.authorization.client_credential_key =
-            config["client_credential_key"]
-          client.authorization.client_credential_secret =
-            config["client_credential_secret"]
-          client.authorization.token_credential_key =
-            config["token_credential_key"]
-          client.authorization.token_credential_secret =
-            config["token_credential_secret"]
-          if client.authorization.token_credential == nil
-            authorization_type = :two_legged_oauth_1
-          end
-        end
-
         if options[:uri]
           # Make request with URI manually specified
           uri = Addressable::URI.parse(options[:uri])
@@ -345,13 +445,8 @@ HTML
           method = options[:http_method]
           method ||= request_body == '' ? 'GET' : 'POST'
           method.upcase!
-          client = Google::APIClient.new(:authorization => authorization_type)
-          if options[:discovery_uri]
-            client.discovery_uri = options[:discovery_uri]
-          end
-          configure_authorization.call(client) if signed
           request = [method, uri.to_str, headers, [request_body]]
-          request = client.sign_request(request)
+          request = client.generate_authenticated_request(:request => request)
           response = client.transmit_request(request)
           status, headers, body = response
           puts body
@@ -362,25 +457,14 @@ HTML
             STDERR.puts('No rpcname supplied.')
             exit(1)
           end
-          service_name =
-            options[:service_name] || self.rpcname[/^([^\.]+)\./, 1]
-          client = Google::APIClient.new(
-            :service => service_name,
-            :authorization => authorization_type
-          )
-          if options[:discovery_uri]
-            client.discovery_uri = options[:discovery_uri]
-          end
-          configure_authorization.call(client) if signed
-          service_version =
-            options[:service_version] ||
-            client.latest_service_version(service_name).version
-          service = client.discovered_service(service_name, service_version)
+          api = options[:api] || self.rpcname[/^([^\.]+)\./, 1]
+          version = api_version(api, options[:version])
+          service = client.discovered_api(api, version)
           method = service.to_h[self.rpcname]
           if !method
             STDERR.puts(
               "Method #{self.rpcname} does not exist for " +
-              "#{service_name}-#{service_version}."
+              "#{api}-#{version}."
             )
             exit(1)
           end
@@ -394,7 +478,7 @@ HTML
           end
           begin
             response = client.execute(
-              method, parameters, request_body, headers, {:signed => signed}
+              method, parameters, request_body, headers
             )
             status, headers, body = response
             puts body
@@ -407,37 +491,7 @@ HTML
       end
 
       def irb
-        require 'signet/oauth_1/client'
-        require 'yaml'
-        require 'irb'
-        config_file = File.expand_path('~/.google-api.yaml')
-        signed = File.exist?(config_file)
-
-        $client = Google::APIClient.new(
-          :service => options[:service_name],
-          :authorization => (signed ? :oauth_1 : nil)
-        )
-
-        if signed
-          if $client.authorization &&
-              !$client.authorization.kind_of?(Signet::OAuth1::Client)
-            STDERR.puts(
-              "Unexpected authorization mechanism: " +
-              "#{$client.authorization.class}"
-            )
-            exit(1)
-          end
-          config = open(config_file, 'r') { |file| YAML.load(file.read) }
-          $client.authorization.client_credential_key =
-            config["client_credential_key"]
-          $client.authorization.client_credential_secret =
-            config["client_credential_secret"]
-          $client.authorization.token_credential_key =
-            config["token_credential_key"]
-          $client.authorization.token_credential_secret =
-            config["token_credential_secret"]
-        end
-
+        $client = self.client
         # Otherwise IRB will misinterpret command-line options
         ARGV.clear
         IRB.start(__FILE__)

data/lib/google/api_client.rb

@@ -12,56 +12,132 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require 'httpadapter'
 require 'json'
 require 'stringio'
 
+require 'google/api_client/errors'
+require 'google/api_client/environment'
 require 'google/api_client/discovery'
 
 module Google
   # TODO(bobaman): Document all this stuff.
 
+
   ##
-  # This class manages communication with a single API.
+  # This class manages APIs communication.
   class APIClient
     ##
-    # An error which is raised when there is an unexpected response or other
-    # transport error that prevents an operation from succeeding.
-    class TransmissionError < StandardError
-    end
-
+    # Creates a new Google API client.
+    #
+    # @param [Hash] options The configuration parameters for the client.
+    # @option options [Symbol, #generate_authenticated_request] :authorization
+    #   (:oauth_1)
+    #   The authorization mechanism used by the client.  The following
+    #   mechanisms are supported out-of-the-box:
+    #   <ul>
+    #     <li><code>:two_legged_oauth_1</code></li>
+    #     <li><code>:oauth_1</code></li>
+    #     <li><code>:oauth_2</code></li>
+    #   </ul>
+    # @option options [String] :host ("www.googleapis.com")
+    #   The API hostname used by the client.  This rarely needs to be changed.
+    # @option options [String] :application_name
+    #   The name and version of the application using the client. This should
+    #   be given in the form `"{name}/{version}"`.
+    # @option options [String] :user_agent
+    #   ("{app_name} google-api-ruby-client/{version} {os_name}/{os_version}")
+    #   The user agent used by the client.  Most developers will want to
+    #   leave this value alone and use the `:application_name` option instead.
     def initialize(options={})
-      @options = {
-        # TODO: What configuration options need to go here?
-      }.merge(options)
-      # Force immediate type-checking and short-cut resolution
-      self.parser
-      self.authorization
-      self.http_adapter
+      # Normalize key to String to allow indifferent access.
+      options = options.inject({}) do |accu, (key, value)|
+        accu[key.to_s] = value
+        accu
+      end
+      # Almost all API usage will have a host of 'www.googleapis.com'.
+      self.host = options["host"] || 'www.googleapis.com'
+      # Most developers will want to leave this value alone and use the
+      # application_name option.
+      self.user_agent = options["user_agent"] || (
+        (options["application_name"] || '')
+        '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
+      # 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.
+      if options["http_adapter"]
+        self.http_adapter = options["http_adapter"]
+      else
+        require 'httpadapter/adapters/net_http'
+        # NOTE: Do not rely on this default value, as it may change
+        self.http_adapter = HTTPAdapter::NetHTTPAdapter.new
+      end
+      @discovery_uris = {}
+      @discovery_documents = {}
+      @discovered_apis = {}
       return self
     end
 
+
     ##
     # Returns the parser used by the client.
-    def parser
-      unless @options[:parser]
-        require 'google/api_client/parsers/json_parser'
-        # NOTE: Do not rely on this default value, as it may change
-        @options[:parser] = JSONParser
+    #
+    # @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
-      return @options[:parser]
+      @parser = new_parser
     end
 
     ##
     # Returns the authorization mechanism used by the client.
     #
     # @return [#generate_authenticated_request] The authorization mechanism.
-    def authorization
-      case @options[:authorization]
+    attr_reader :authorization
+
+    ##
+    # Sets the authorization mechanism used by the client.
+    #
+    # @param [#generate_authenticated_request] new_authorization
+    #   The new authorization mechanism.
+    def authorization=(new_authorization)
+      case new_authorization
       when :oauth_1, :oauth
         require 'signet/oauth_1/client'
         # NOTE: Do not rely on this default value, as it may change
-        @options[:authorization] = Signet::OAuth1::Client.new(
+        new_authorization = Signet::OAuth1::Client.new(
           :temporary_credential_uri =>
             'https://www.google.com/accounts/OAuthGetRequestToken',
           :authorization_uri =>
@@ -74,79 +150,175 @@ module Google
       when :two_legged_oauth_1, :two_legged_oauth
         require 'signet/oauth_1/client'
         # NOTE: Do not rely on this default value, as it may change
-        @options[:authorization] = Signet::OAuth1::Client.new(
+        new_authorization = Signet::OAuth1::Client.new(
           :client_credential_key => nil,
           :client_credential_secret => nil,
           :two_legged => true
         )
+      when :oauth_2
+        require 'signet/oauth_2/client'
+        # NOTE: Do not rely on this default value, as it may change
+        new_authorization = Signet::OAuth2::Client.new(
+          :authorization_uri =>
+            'https://accounts.google.com/o/oauth2/auth',
+          :token_credential_uri =>
+            'https://accounts.google.com/o/oauth2/token'
+        )
       when nil
         # No authorization mechanism
       else
-        if !@options[:authorization].respond_to?(
-            :generate_authenticated_request)
+        if !new_authorization.respond_to?(:generate_authenticated_request)
           raise TypeError,
             'Expected authorization mechanism to respond to ' +
             '#generate_authenticated_request.'
         end
       end
-      return @options[:authorization]
+      @authorization = new_authorization
+      return @authorization
     end
 
     ##
-    # Sets the authorization mechanism used by the client.
+    # Returns the HTTP adapter used by the client.
     #
-    # @param [#generate_authenticated_request] new_authorization
-    #   The new authorization mechanism.
-    def authorization=(new_authorization)
-      @options[:authorization] = new_authorization
-      return self.authorization
-    end
+    # @return [HTTPAdapter]
+    #   The HTTP adapter object.  The object must include the
+    #   HTTPAdapter module and conform to its interface.
+    attr_reader :http_adapter
 
     ##
     # Returns the HTTP adapter used by the client.
-    def http_adapter
-      return @options[:http_adapter] ||= (begin
-        require 'httpadapter/adapters/net_http'
-        @options[:http_adapter] = HTTPAdapter::NetHTTPRequestAdapter
-      end)
+    #
+    # @return [HTTPAdapter]
+    #   The HTTP adapter object.  The object must include the
+    #   HTTPAdapter module and conform to its interface.
+    def http_adapter=(new_http_adapter)
+      if new_http_adapter.kind_of?(HTTPAdapter)
+        @http_adapter = new_http_adapter
+      else
+        raise TypeError, "Expected HTTPAdapter, got #{new_http_adapter.class}."
+      end
+    end
+
+    ##
+    # The API hostname used by the client.
+    #
+    # @return [String]
+    #   The API hostname.  Should almost always be 'www.googleapis.com'.
+    attr_accessor :host
+
+    ##
+    # The user agent used by the client.
+    #
+    # @return [String]
+    #   The user agent string used in the User-Agent header.
+    attr_accessor :user_agent
+
+    ##
+    # Returns the URI for the directory document.
+    #
+    # @return [Addressable::URI] The URI of the directory document.
+    def directory_uri
+      template = Addressable::Template.new(
+        "https://{host}/discovery/v1/apis"
+      )
+      return template.expand({"host" => self.host})
+    end
+
+    ##
+    # Manually registers a URI as a discovery document for a specific version
+    # of an API.
+    #
+    # @param [String, Symbol] api The service name.
+    # @param [String] version The desired version of the service.
+    # @param [Addressable::URI] uri The URI of the discovery document.
+    def register_discovery_uri(api, version, uri)
+      api = api.to_s
+      version = version || 'v1'
+      @discovery_uris["#{api}:#{version}"] = uri
     end
 
     ##
     # Returns the URI for the discovery document.
     #
+    # @param [String, Symbol] api The service name.
+    # @param [String] version The desired version of the service.
     # @return [Addressable::URI] The URI of the discovery document.
-    def discovery_uri
-      return @options[:discovery_uri] ||= (begin
-        if @options[:service]
-          service_id = @options[:service]
-          service_version = @options[:service_version] || 'v1'
-          Addressable::URI.parse(
-            "http://www.googleapis.com/discovery/0.1/describe" +
-            "?api=#{service_id}"
-          )
-        else
-          raise ArgumentError,
-            'Missing required configuration value, :discovery_uri.'
-        end
+    def discovery_uri(api, version=nil)
+      api = api.to_s
+      version = version || 'v1'
+      return @discovery_uris["#{api}:#{version}"] ||= (begin
+        template = Addressable::Template.new(
+          "https://{host}/discovery/v1/apis/" +
+          "{api}/{version}/rest"
+        )
+        template.expand({
+          "host" => self.host,
+          "api" => api,
+          "version" => version
+        })
       end)
     end
 
     ##
-    # Sets the discovery URI for the client.
+    # Manually registers a pre-loaded discovery document for a specific version
+    # of an API.
     #
-    # @param [Addressable::URI, #to_str, String] new_discovery_uri
-    #   The new discovery URI.
-    def discovery_uri=(new_discovery_uri)
-      @options[:discovery_uri] = Addressable::URI.parse(new_discovery_uri)
+    # @param [String, Symbol] api The service name.
+    # @param [String] version The desired version of the service.
+    # @param [String, StringIO] discovery_document
+    #   The contents of the discovery document.
+    def register_discovery_document(api, version, discovery_document)
+      api = api.to_s
+      version = version || 'v1'
+      if discovery_document.kind_of?(StringIO)
+        discovery_document.rewind
+        discovery_document = discovery_document.string
+      elsif discovery_document.respond_to?(:to_str)
+        discovery_document = discovery_document.to_str
+      else
+        raise TypeError,
+          "Expected String or StringIO, got #{discovery_document.class}."
+      end
+      @discovery_documents["#{api}:#{version}"] =
+        JSON.parse(discovery_document)
+    end
+
+    ##
+    # Returns the parsed directory document.
+    #
+    # @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)
+        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)
+          end
+          merged_body.rewind
+          JSON.parse(merged_body.string)
+        else
+          raise TransmissionError,
+            "Could not retrieve discovery document at: #{request_uri}"
+        end
+      end)
     end
 
     ##
     # Returns the parsed discovery document.
     #
+    # @param [String, Symbol] api The service name.
+    # @param [String] version The desired version of the service.
     # @return [Hash] The parsed JSON from the discovery document.
-    def discovery_document
-      return @discovery_document ||= (begin
-        request = ['GET', self.discovery_uri.to_s, [], []]
+    def discovery_document(api, version=nil)
+      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)
         status, headers, body = response
         if status == 200 # TODO(bobaman) Better status code handling?
@@ -158,101 +330,102 @@ module Google
           JSON.parse(merged_body.string)
         else
           raise TransmissionError,
-            "Could not retrieve discovery document at: #{self.discovery_uri}"
+            "Could not retrieve discovery document at: #{request_uri}"
         end
       end)
     end
 
     ##
-    # Returns a list of services this client instance has performed discovery
-    # for.  This may return multiple versions of the same service.
-    #
-    # @return [Array]
-    #   A list of discovered <code>Google::APIClient::Service</code> objects.
-    def discovered_services
-      return @discovered_services ||= (begin
-        service_names = self.discovery_document['data'].keys()
-        services = []
-        for service_name in service_names
-          versions = self.discovery_document['data'][service_name]
-          for service_version in versions.keys()
-            service_description =
-              self.discovery_document['data'][service_name][service_version]
-            services << ::Google::APIClient::Service.new(
-              service_name,
-              service_version,
-              service_description
+    # Returns all APIs published in the directory document.
+    #
+    # @return [Array] The list of available APIs.
+    def discovered_apis
+      @directory_apis ||= (begin
+        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(
+              document_base,
+              discovery_document
             )
           end
+        else
+          []
         end
-        services
       end)
     end
 
     ##
     # Returns the service object for a given service name and service version.
     #
-    # @param [String, Symbol] service_name The service name.
-    # @param [String] service_version The desired version of the service.
+    # @param [String, Symbol] api The service name.
+    # @param [String] version The desired version of the service.
     #
-    # @return [Google::APIClient::Service] The service object.
-    def discovered_service(service_name, service_version='v1')
-      if !service_name.kind_of?(String) && !service_name.kind_of?(Symbol)
+    # @return [Google::APIClient::API] The service object.
+    def discovered_api(api, version=nil)
+      if !api.kind_of?(String) && !api.kind_of?(Symbol)
         raise TypeError,
-          "Expected String or Symbol, got #{service_name.class}."
+          "Expected String or Symbol, got #{api.class}."
       end
-      service_name = service_name.to_s
-      for service in self.discovered_services
-        if service.name == service_name &&
-            service.version.to_s == service_version.to_s
-          return service
+      api = api.to_s
+      version = version || 'v1'
+      return @discovered_apis["#{api}:#{version}"] ||= begin
+        document_base = self.discovery_uri(api, version)
+        discovery_document = self.discovery_document(api, version)
+        if document_base && discovery_document
+          ::Google::APIClient::API.new(
+            document_base,
+            discovery_document
+          )
+        else
+          nil
         end
       end
-      return nil
     end
 
     ##
     # Returns the method object for a given RPC name and service version.
     #
     # @param [String, Symbol] rpc_name The RPC name of the desired method.
-    # @param [String] service_version The desired version of the service.
+    # @param [String] version The desired version of the service.
     #
     # @return [Google::APIClient::Method] The method object.
-    def discovered_method(rpc_name, service_version='v1')
+    def discovered_method(rpc_name, api, version=nil)
       if !rpc_name.kind_of?(String) && !rpc_name.kind_of?(Symbol)
         raise TypeError,
           "Expected String or Symbol, got #{rpc_name.class}."
       end
       rpc_name = rpc_name.to_s
-      for service in self.discovered_services
-        # This looks kinda weird, but is not a real problem because there's
-        # almost always only one service, and this is memoized anyhow.
-        if service.version.to_s == service_version.to_s
-          return service.to_h[rpc_name] if service.to_h[rpc_name]
-        end
+      api = api.to_s
+      version = version || 'v1'
+      service = self.discovered_api(api, version)
+      if service.to_h[rpc_name]
+        return service.to_h[rpc_name]
+      else
+        return nil
       end
-      return nil
     end
 
     ##
     # Returns the service object with the highest version number.
     #
-    # <em>Warning</em>: This method should be used with great care. As APIs
-    # are updated, minor differences between versions may cause
+    # @note <em>Warning</em>: This method should be used with great care.
+    # As APIs are updated, minor differences between versions may cause
     # incompatibilities. Requesting a specific version will avoid this issue.
     #
-    # @param [String, Symbol] service_name The name of the service.
+    # @param [String, Symbol] api The name of the service.
     #
-    # @return [Google::APIClient::Service] The service object.
-    def latest_service_version(service_name)
-      if !service_name.kind_of?(String) && !service_name.kind_of?(Symbol)
+    # @return [Google::APIClient::API] The service object.
+    def preferred_version(api)
+      if !api.kind_of?(String) && !api.kind_of?(Symbol)
         raise TypeError,
-          "Expected String or Symbol, got #{service_name.class}."
+          "Expected String or Symbol, got #{api.class}."
+      end
+      api = api.to_s
+      # TODO(bobaman): Update to use directory API.
+      return self.discovered_apis.detect do |a|
+        a.name == api && a.preferred == true
       end
-      service_name = service_name.to_s
-      return (self.discovered_services.select do |service|
-        service.name == service_name
-      end).sort.last
     end
 
     ##
@@ -266,16 +439,17 @@ module Google
     # @param [Hash, Array] headers The HTTP headers for the request.
     # @param [Hash] options
     #   The configuration parameters for the request.
-    #   - <code>:service_version</code> — 
+    #   - <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>:signed</code> is <code>true</code>.
-    #   - <code>:signed</code> — 
-    #     <code>true</code> if the request must be signed, <code>false</code>
+    #     <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> if an authorization
     #     mechanism has been set, <code>false</code> otherwise.
     #
@@ -291,19 +465,27 @@ module Google
         api_method, parameters={}, body='', headers=[], options={})
       options={
         :parser => self.parser,
-        :service_version => 'v1',
+        :version => 'v1',
         :authorization => self.authorization
       }.merge(options)
-      # The default value for the :signed option depends on whether an
+      # The default value for the :authenticated option depends on whether an
       # authorization mechanism has been set.
       if options[:authorization]
-        options = {:signed => true}.merge(options)
+        options = {:authenticated => true}.merge(options)
       else
-        options = {:signed => false}.merge(options)
+        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.to_s, options[:service_version]
+          api_method, api, options[:version]
         )
       elsif !api_method.kind_of?(::Google::APIClient::Method)
         raise TypeError,
@@ -314,8 +496,8 @@ module Google
         raise ArgumentError, "API method could not be found."
       end
       request = api_method.generate_request(parameters, body, headers)
-      if options[:signed]
-        request = self.sign_request(request, options[:authorization])
+      if options[:authenticated]
+        request = self.generate_authenticated_request(:request => request)
       end
       return request
     end
@@ -331,7 +513,7 @@ module Google
     # @param [Hash, Array] headers The HTTP headers for the request.
     # @param [Hash] options
     #   The configuration parameters for the request.
-    #   - <code>:service_version</code> — 
+    #   - <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> — 
@@ -340,9 +522,10 @@ module Google
     #     The parser for the response.
     #   - <code>:authorization</code> — 
     #     The authorization mechanism for the response.  Used only if
-    #     <code>:signed</code> is <code>true</code>.
-    #   - <code>:signed</code> — 
-    #     <code>true</code> if the request must be signed, <code>false</code>
+    #     <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 response from the API.
@@ -371,21 +554,36 @@ module Google
     #
     # @return [Array] The response from the server.
     def transmit_request(request, adapter=self.http_adapter)
-      ::HTTPAdapter.transmit(request, adapter)
+      if self.user_agent != nil
+        # If there's no User-Agent header, set one.
+        method, uri, headers, body = request
+        unless headers.kind_of?(Enumerable)
+          # We need to use some Enumerable methods, relying on the presence of
+          # the #each method.
+          class <<headers
+            include Enumerable
+          end
+        end
+        if self.user_agent.kind_of?(String)
+          unless headers.any? { |k, v| k.downcase == 'User-Agent'.downcase }
+            headers = headers.to_a.insert(0, ['User-Agent', self.user_agent])
+          end
+        elsif self.user_agent != nil
+          raise TypeError,
+            "Expected User-Agent to be String, got #{self.user_agent.class}"
+        end
+      end
+      adapter.transmit([method, uri, headers, body])
     end
 
     ##
     # Signs a request using the current authorization mechanism.
     #
-    # @param [Array] request The request to sign.
-    # @param [#generate_authenticated_request] authorization
-    #   The authorization mechanism.
+    # @param [Hash] options The options to pass through.
     #
-    # @return [Array] The signed request.
-    def sign_request(request, authorization=self.authorization)
-      return authorization.generate_authenticated_request(
-        :request => request
-      )
+    # @return [Array] The signed or otherwise authenticated request.
+    def generate_authenticated_request(options={})
+      return authorization.generate_authenticated_request(options)
     end
   end
 end