google-api-client 0.1.0

data/lib/google/api_client.rb

@@ -0,0 +1,375 @@
+# Copyright 2010 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'httpadapter'
+require 'json'
+
+require 'google/api_client/discovery'
+
+module Google
+  # TODO(bobaman): Document all this stuff.
+
+  ##
+  # This class manages communication with a single API.
+  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
+
+    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
+      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
+      end
+      return @options[:parser]
+    end
+
+    ##
+    # Returns the authorization mechanism used by the client.
+    #
+    # @return [#generate_authenticated_request] The authorization mechanism.
+    def authorization
+      case @options[: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(
+          :temporary_credential_uri =>
+            'https://www.google.com/accounts/OAuthGetRequestToken',
+          :authorization_uri =>
+            'https://www.google.com/accounts/OAuthAuthorizeToken',
+          :token_credential_uri =>
+            'https://www.google.com/accounts/OAuthGetAccessToken',
+          :client_credential_key => 'anonymous',
+          :client_credential_secret => 'anonymous'
+        )
+      when nil
+        # No authorization mechanism
+      else
+        if !@options[:authorization].respond_to?(
+            :generate_authenticated_request)
+          raise TypeError,
+            'Expected authorization mechanism to respond to ' +
+            '#generate_authenticated_request.'
+        end
+      end
+      return @options[:authorization]
+    end
+
+    ##
+    # Sets the authorization mechanism 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
+
+    ##
+    # 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)
+    end
+
+    ##
+    # Returns the URI for the discovery document.
+    #
+    # @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
+      end)
+    end
+
+    ##
+    # Returns the parsed discovery document.
+    #
+    # @return [Hash] The parsed JSON from the discovery document.
+    def discovery_document
+      return @discovery_document ||= (begin
+        request = ['GET', self.discovery_uri.to_s, [], []]
+        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: #{self.discovery_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
+            )
+          end
+        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.
+    #
+    # @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)
+        raise TypeError,
+          "Expected String or Symbol, got #{service_name.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
+        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.
+    #
+    # @return [Google::APIClient::Method] The method object.
+    def discovered_method(rpc_name, service_version='v1')
+      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
+      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
+    # incompatibilities. Requesting a specific version will avoid this issue.
+    #
+    # @param [String, Symbol] service_name 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)
+        raise TypeError,
+          "Expected String or Symbol, got #{service_name.class}."
+      end
+      service_name = service_name.to_s
+      return (self.discovered_services.select do |service|
+        service.name == service_name
+      end).sort.last
+    end
+
+    ##
+    # Generates a request.
+    #
+    # @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>:service_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>
+    #     otherwise.  Defaults to <code>true</code> if an authorization
+    #     mechanism has been set, <code>false</code> otherwise.
+    #
+    # @return [Array] The generated request.
+    #
+    # @example
+    #   request = client.generate_request(
+    #     'chili.activities.list',
+    #     {'scope' => '@self', 'userId' => '@me', 'alt' => 'json'}
+    #   )
+    #   method, uri, headers, body = request
+    def generate_request(
+        api_method, parameters={}, body='', headers=[], options={})
+      options={
+        :parser => self.parser,
+        :service_version => 'v1',
+        :authorization => self.authorization
+      }.merge(options)
+      # The default value for the :signed option depends on whether an
+      # authorization mechanism has been set.
+      if options[:authorization]
+        options = {:signed => true}.merge(options)
+      else
+        options = {:signed => false}.merge(options)
+      end
+      if api_method.kind_of?(String) || api_method.kind_of?(Symbol)
+        api_method = self.discovered_method(
+          api_method.to_s, options[:service_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)
+      if options[:signed]
+        request = self.sign_request(request, options[:authorization])
+      end
+      return request
+    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>:service_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>:signed</code> is <code>true</code>.
+    #   - <code>:signed</code> — 
+    #     <code>true</code> if the request must be signed, <code>false</code>
+    #     otherwise.  Defaults to <code>true</code>.
+    #
+    # @return [Array] The response from the API.
+    #
+    # @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
+      )
+    end
+
+    ##
+    # Transmits the request using the current HTTP adapter.
+    #
+    # @param [Array] request The request to transmit.
+    # @param [#transmit] adapter The HTTP adapter.
+    #
+    # @return [Array] The response from the server.
+    def transmit_request(request, adapter=self.http_adapter)
+      ::HTTPAdapter.transmit(request, adapter)
+    end
+
+    ##
+    # Signs a request using the current authorization mechanism.
+    #
+    # @param [Array] request The request to sign.
+    # @param [#generate_authenticated_request] authorization
+    #   The authorization mechanism.
+    #
+    # @return [Array] The signed request.
+    def sign_request(request, authorization=self.authorization)
+      return authorization.generate_authenticated_request(
+        :request => request
+      )
+    end
+  end
+end
+
+require 'google/api_client/version'

data/lib/google/api_client/discovery.rb

@@ -0,0 +1,535 @@
+# Copyright 2010 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'json'
+require 'addressable/uri'
+require 'addressable/template'
+require 'extlib/inflection'
+
+module Google
+  class APIClient
+    ##
+    # An exception that is raised if a method is called with missing or
+    # invalid parameter values.
+    class ValidationError < StandardError
+    end
+
+    ##
+    # A service that has been described by a discovery document.
+    class Service
+
+      ##
+      # Creates a description of a particular version of a service.
+      #
+      # @param [String] service_name
+      #   The identifier for the service.  Note that while this frequently
+      #   matches the first segment of all of the service's RPC names, this
+      #   should not be assumed.  There is no requirement that these match.
+      # @param [String] service_version
+      #   The identifier for the service version.
+      # @param [Hash] service_description
+      #   The section of the discovery document that applies to this service
+      #   version.
+      #
+      # @return [Google::APIClient::Service] The constructed service object.
+      def initialize(service_name, service_version, service_description)
+        @name = service_name
+        @version = service_version
+        @description = service_description
+        metaclass = (class <<self; self; end)
+        self.resources.each do |resource|
+          method_name = Extlib::Inflection.underscore(resource.name).to_sym
+          if !self.respond_to?(method_name)
+            metaclass.send(:define_method, method_name) { resource }
+          end
+        end
+        self.methods.each do |method|
+          method_name = Extlib::Inflection.underscore(method.name).to_sym
+          if !self.respond_to?(method_name)
+            metaclass.send(:define_method, method_name) { method }
+          end
+        end
+      end
+
+      ##
+      # Returns the identifier for the service.
+      #
+      # @return [String] The service identifier.
+      attr_reader :name
+
+      ##
+      # Returns the version of the service.
+      #
+      # @return [String] The service version.
+      attr_reader :version
+
+      ##
+      # Returns the parsed section of the discovery document that applies to
+      # this version of the service.
+      #
+      # @return [Hash] The service description.
+      attr_reader :description
+
+      ##
+      # Returns the base URI for this version of the service.
+      #
+      # @return [Addressable::URI] The base URI that methods are joined to.
+      def base
+        return @base ||= Addressable::URI.parse(self.description['baseUrl'])
+      end
+
+      ##
+      # A list of resources available at the root level of this version of the
+      # service.
+      #
+      # @return [Array] A list of {Google::APIClient::Resource} objects.
+      def resources
+        return @resources ||= (
+          (self.description['resources'] || []).inject([]) do |accu, (k, v)|
+            accu << ::Google::APIClient::Resource.new(self.base, k, v)
+            accu
+          end
+        )
+      end
+
+      ##
+      # A list of methods available at the root level of this version of the
+      # service.
+      #
+      # @return [Array] A list of {Google::APIClient::Method} objects.
+      def methods
+        return @methods ||= (
+          (self.description['methods'] || []).inject([]) do |accu, (k, v)|
+            accu << ::Google::APIClient::Method.new(self.base, k, v)
+            accu
+          end
+        )
+      end
+
+      ##
+      # Converts the service to a flat mapping of RPC names and method objects.
+      #
+      # @return [Hash] All methods available on the service.
+      #
+      # @example
+      #   # Discover available methods
+      #   method_names = client.discovered_service('buzz').to_h.keys
+      def to_h
+        return @hash ||= (begin
+          methods_hash = {}
+          self.methods.each do |method|
+            methods_hash[method.rpc_name] = method
+          end
+          self.resources.each do |resource|
+            methods_hash.merge!(resource.to_h)
+          end
+          methods_hash
+        end)
+      end
+
+      ##
+      # Compares two versions of a service.
+      #
+      # @param [Object] other The service to compare.
+      #
+      # @return [Integer]
+      #   <code>-1</code> if the service is older than <code>other</code>.
+      #   <code>0</code> if the service is the same as <code>other</code>.
+      #   <code>1</code> if the service is newer than <code>other</code>.
+      #   <code>nil</code> if the service cannot be compared to
+      #   <code>other</code>.
+      def <=>(other)
+        # We can only compare versions of the same service
+        if other.kind_of?(self.class) && self.name == other.name
+          split_version = lambda do |version|
+            dotted_version = version[/^v?(\d+(.\d+)*)-?(.*?)?$/, 1]
+            suffix = version[/^v?(\d+(.\d+)*)-?(.*?)?$/, 3]
+            [dotted_version.split('.').map { |v| v.to_i }, suffix]
+          end
+          self_sortable, self_suffix = split_version.call(self.version)
+          other_sortable, other_suffix = split_version.call(other.version)
+          result = self_sortable <=> other_sortable
+          if result != 0
+            return result
+          # If the dotted versions are equal, check the suffix.
+          # An omitted suffix should be sorted after an included suffix.
+          elsif self_suffix == ''
+            return 1
+          elsif other_suffix == ''
+            return -1
+          else
+            return self_suffix <=> other_suffix
+          end
+        else
+          return nil
+        end
+      end
+
+      ##
+      # Returns a <code>String</code> representation of the service's state.
+      #
+      # @return [String] The service's state, as a <code>String</code>.
+      def inspect
+        sprintf(
+          "#<%s:%#0x NAME:%s>", self.class.to_s, self.object_id, self.name
+        )
+      end
+    end
+
+    ##
+    # A resource that has been described by a discovery document.
+    class Resource
+
+      ##
+      # Creates a description of a particular version of a resource.
+      #
+      # @param [Addressable::URI] base
+      #   The base URI for the service.
+      # @param [String] resource_name
+      #   The identifier for the resource.
+      # @param [Hash] resource_description
+      #   The section of the discovery document that applies to this resource.
+      #
+      # @return [Google::APIClient::Resource] The constructed resource object.
+      def initialize(base, resource_name, resource_description)
+        @base = base
+        @name = resource_name
+        @description = resource_description
+        metaclass = (class <<self; self; end)
+        self.resources.each do |resource|
+          method_name = Extlib::Inflection.underscore(resource.name).to_sym
+          if !self.respond_to?(method_name)
+            metaclass.send(:define_method, method_name) { resource }
+          end
+        end
+        self.methods.each do |method|
+          method_name = Extlib::Inflection.underscore(method.name).to_sym
+          if !self.respond_to?(method_name)
+            metaclass.send(:define_method, method_name) { method }
+          end
+        end
+      end
+
+      ##
+      # Returns the identifier for the resource.
+      #
+      # @return [String] The resource identifier.
+      attr_reader :name
+
+      ##
+      # Returns the parsed section of the discovery document that applies to
+      # this resource.
+      #
+      # @return [Hash] The resource description.
+      attr_reader :description
+
+      ##
+      # Returns the base URI for this resource.
+      #
+      # @return [Addressable::URI] The base URI that methods are joined to.
+      attr_reader :base
+
+      ##
+      # A list of sub-resources available on this resource.
+      #
+      # @return [Array] A list of {Google::APIClient::Resource} objects.
+      def resources
+        return @resources ||= (
+          (self.description['resources'] || []).inject([]) do |accu, (k, v)|
+            accu << ::Google::APIClient::Resource.new(self.base, k, v)
+            accu
+          end
+        )
+      end
+
+      ##
+      # A list of methods available on this resource.
+      #
+      # @return [Array] A list of {Google::APIClient::Method} objects.
+      def methods
+        return @methods ||= (
+          (self.description['methods'] || []).inject([]) do |accu, (k, v)|
+            accu << ::Google::APIClient::Method.new(self.base, k, v)
+            accu
+          end
+        )
+      end
+
+      ##
+      # Converts the resource to a flat mapping of RPC names and method
+      # objects.
+      #
+      # @return [Hash] All methods available on the resource.
+      def to_h
+        return @hash ||= (begin
+          methods_hash = {}
+          self.methods.each do |method|
+            methods_hash[method.rpc_name] = method
+          end
+          self.resources.each do |resource|
+            methods_hash.merge!(resource.to_h)
+          end
+          methods_hash
+        end)
+      end
+
+      ##
+      # Returns a <code>String</code> representation of the resource's state.
+      #
+      # @return [String] The resource's state, as a <code>String</code>.
+      def inspect
+        sprintf(
+          "#<%s:%#0x NAME:%s>", self.class.to_s, self.object_id, self.name
+        )
+      end
+    end
+
+    ##
+    # A method that has been described by a discovery document.
+    class Method
+
+      ##
+      # Creates a description of a particular method.
+      #
+      # @param [Addressable::URI] base
+      #   The base URI for the service.
+      # @param [String] method_name
+      #   The identifier for the method.
+      # @param [Hash] method_description
+      #   The section of the discovery document that applies to this method.
+      #
+      # @return [Google::APIClient::Method] The constructed method object.
+      def initialize(base, method_name, method_description)
+        @base = base
+        @name = method_name
+        @description = method_description
+      end
+
+      ##
+      # Returns the identifier for the method.
+      #
+      # @return [String] The method identifier.
+      attr_reader :name
+
+      ##
+      # Returns the parsed section of the discovery document that applies to
+      # this method.
+      #
+      # @return [Hash] The method description.
+      attr_reader :description
+
+      ##
+      # Returns the base URI for the method.
+      #
+      # @return [Addressable::URI]
+      #   The base URI that this method will be joined to.
+      attr_reader :base
+
+      ##
+      # Returns the RPC name for the method.
+      #
+      # @return [String] The RPC name.
+      def rpc_name
+        return self.description['rpcName']
+      end
+
+      ##
+      # Returns the URI template for the method.  A parameter list can be
+      # used to expand this into a URI.
+      #
+      # @return [Addressable::Template] The URI template.
+      def uri_template
+        # TODO(bobaman) We shouldn't be calling #to_s here, this should be
+        # a join operation on a URI, but we have to treat these as Strings
+        # because of the way the discovery document provides the URIs.
+        # This should be fixed soon.
+        return @uri_template ||=
+          Addressable::Template.new(base.to_s + self.description['pathUrl'])
+      end
+
+      ##
+      # Normalizes parameters, converting to the appropriate types.
+      #
+      # @param [Hash, Array] parameters
+      #   The parameters to normalize.
+      #
+      # @return [Hash] The normalized parameters.
+      def normalize_parameters(parameters={})
+        # Convert keys to Strings when appropriate
+        if parameters.kind_of?(Hash) || parameters.kind_of?(Array)
+          # Is a Hash or an Array a better return type?  Do we ever need to
+          # worry about the same parameter being sent twice with different
+          # values?
+          parameters = parameters.inject({}) do |accu, (k, v)|
+            k = k.to_s if k.kind_of?(Symbol)
+            k = k.to_str if k.respond_to?(:to_str)
+            unless k.kind_of?(String)
+              raise TypeError, "Expected String, got #{k.class}."
+            end
+            accu[k] = v
+            accu
+          end
+        else
+          raise TypeError,
+            "Expected Hash or Array, got #{parameters.class}."
+        end
+        return parameters
+      end
+
+      ##
+      # Expands the method's URI template using a parameter list.
+      #
+      # @param [Hash, Array] parameters
+      #   The parameter list to use.
+      #
+      # @return [Addressable::URI] The URI after expansion.
+      def generate_uri(parameters={})
+        parameters = self.normalize_parameters(parameters)
+        self.validate_parameters(parameters)
+        template_variables = self.uri_template.variables
+        uri = self.uri_template.expand(parameters)
+        query_parameters = parameters.reject do |k, v|
+          template_variables.include?(k)
+        end
+        if query_parameters.size > 0
+          uri.query_values = (uri.query_values || {}).merge(query_parameters)
+        end
+        # Normalization is necessary because of undesirable percent-escaping
+        # during URI template expansion
+        return uri.normalize
+      end
+
+      ##
+      # Generates an HTTP request for this method.
+      #
+      # @param [Hash, Array] parameters
+      #   The parameters to send.
+      # @param [String, StringIO] body The body for the HTTP request.
+      # @param [Hash, Array] headers The HTTP headers for the request.
+      #
+      # @return [Array] The generated HTTP request.
+      def generate_request(parameters={}, body='', headers=[])
+        if body.respond_to?(:string)
+          body = body.string
+        elsif body.respond_to?(:to_str)
+          body = body.to_str
+        else
+          raise TypeError, "Expected String or StringIO, got #{body.class}."
+        end
+        if !headers.kind_of?(Array) && !headers.kind_of?(Hash)
+          raise TypeError, "Expected Hash or Array, got #{headers.class}."
+        end
+        method = self.description['httpMethod'] || 'GET'
+        uri = self.generate_uri(parameters)
+        headers = headers.to_a if headers.kind_of?(Hash)
+        return [method, uri.to_str, headers, [body]]
+      end
+
+      ##
+      # Returns a <code>Hash</code> of the parameter descriptions for
+      # this method.
+      #
+      # @return [Hash] The parameter descriptions.
+      def parameter_descriptions
+        @parameter_descriptions ||= (
+          self.description['parameters'] || {}
+        ).inject({}) { |h,(k,v)| h[k]=v; h }
+      end
+
+      ##
+      # Returns an <code>Array</code> of the parameters for this method.
+      #
+      # @return [Array] The parameters.
+      def parameters
+        @parameters ||= ((
+          self.description['parameters'] || {}
+        ).inject({}) { |h,(k,v)| h[k]=v; h }).keys
+      end
+
+      ##
+      # Returns an <code>Array</code> of the required parameters for this
+      # method.
+      #
+      # @return [Array] The required parameters.
+      #
+      # @example
+      #   # A list of all required parameters.
+      #   method.required_parameters
+      def required_parameters
+        @required_parameters ||= ((self.parameter_descriptions.select do |k, v|
+          v['required']
+        end).inject({}) { |h,(k,v)| h[k]=v; h }).keys
+      end
+
+      ##
+      # Returns an <code>Array</code> of the optional parameters for this
+      # method.
+      #
+      # @return [Array] The optional parameters.
+      #
+      # @example
+      #   # A list of all optional parameters.
+      #   method.optional_parameters
+      def optional_parameters
+        @optional_parameters ||= ((self.parameter_descriptions.reject do |k, v|
+          v['required']
+        end).inject({}) { |h,(k,v)| h[k]=v; h }).keys
+      end
+
+      ##
+      # Verifies that the parameters are valid for this method.  Raises an
+      # exception if validation fails.
+      #
+      # @param [Hash, Array] parameters
+      #   The parameters to verify.
+      #
+      # @return [NilClass] <code>nil</code> if validation passes.
+      def validate_parameters(parameters={})
+        parameters = self.normalize_parameters(parameters)
+        required_variables = ((self.parameter_descriptions.select do |k, v|
+          v['required']
+        end).inject({}) { |h,(k,v)| h[k]=v; h }).keys
+        missing_variables = required_variables - parameters.keys
+        if missing_variables.size > 0
+          raise ArgumentError,
+            "Missing required parameters: #{missing_variables.join(', ')}."
+        end
+        parameters.each do |k, v|
+          if self.parameter_descriptions[k]
+            pattern = self.parameter_descriptions[k]['pattern']
+            if pattern
+              regexp = Regexp.new("^#{pattern}$")
+              if v !~ regexp
+                raise ArgumentError,
+                  "Parameter '#{k}' has an invalid value: #{v}. " +
+                  "Must match: /^#{pattern}$/."
+              end
+            end
+          end
+        end
+        return nil
+      end
+
+      ##
+      # Returns a <code>String</code> representation of the method's state.
+      #
+      # @return [String] The method's state, as a <code>String</code>.
+      def inspect
+        sprintf(
+          "#<%s:%#0x NAME:%s>", self.class.to_s, self.object_id, self.rpc_name
+        )
+      end
+    end
+  end
+end