lib/google/api_client/reference.rb

   1 # Copyright 2010 Google Inc.
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #      http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 require 'faraday'
  16 require 'faraday/utils'
  17 require 'multi_json'
  18 require 'compat/multi_json'
  19 require 'addressable/uri'
  20 require 'stringio'
  21 require 'google/api_client/discovery'
  22
  23 module Google
  24   class APIClient
  25
  26     ##
  27     # Represents an API request.
  28     class Request
  29       MULTIPART_BOUNDARY = "-----------RubyApiMultipartPost".freeze
  30
  31       # @return [Hash] Request parameters
  32       attr_reader :parameters
  33       # @return [Hash] Additional HTTP headers
  34       attr_reader :headers
  35       # @return [Google::APIClient::Method] API method to invoke
  36       attr_reader :api_method
  37       # @return [Google::APIClient::UploadIO] File to upload
  38       attr_accessor :media
  39       # @return [#generated_authenticated_request] User credentials
  40       attr_accessor :authorization
  41       # @return [TrueClass,FalseClass] True if request should include credentials
  42       attr_accessor :authenticated
  43       # @return [#read, #to_str] Request body
  44       attr_accessor :body
  45
  46       ##
  47       # Build a request
  48       #
  49       # @param [Hash] options
  50       # @option options [Hash, Array] :parameters
  51       #   Request parameters for the API method.
  52       # @option options [Google::APIClient::Method] :api_method
  53       #   API method to invoke. Either :api_method or :uri must be specified
  54       # @option options [TrueClass, FalseClass] :authenticated
  55       #   True if request should include credentials. Implicitly true if
  56       #   unspecified and :authorization present
  57       # @option options [#generate_signed_request] :authorization
  58       #   OAuth credentials
  59       # @option options [Google::APIClient::UploadIO] :media
  60       #   File to upload, if media upload request
  61       # @option options [#to_json, #to_hash] :body_object
  62       #   Main body of the API request. Typically hash or object that can
  63       #   be serialized to JSON
  64       # @option options [#read, #to_str] :body
  65       #   Raw body to send in POST/PUT requests
  66       # @option options [String, Addressable::URI] :uri
  67       #   URI to request. Either :api_method or :uri must be specified
  68       # @option options [String, Symbol] :http_method
  69       #   HTTP method when requesting a URI
  70       def initialize(options={})
  71         @parameters = Hash[options[:parameters] || {}]
  72         @headers = Faraday::Utils::Headers.new
  73         self.headers.merge!(options[:headers]) unless options[:headers].nil?
  74         self.api_method = options[:api_method]
  75         self.authenticated = options[:authenticated]
  76         self.authorization = options[:authorization]
  77
  78         # These parameters are handled differently because they're not
  79         # parameters to the API method, but rather to the API system.
  80         self.parameters['key'] ||= options[:key] if options[:key]
  81         self.parameters['userIp'] ||= options[:user_ip] if options[:user_ip]
  82
  83         if options[:media]
  84           self.initialize_media_upload(options)
  85         elsif options[:body]
  86           self.body = options[:body]
  87         elsif options[:body_object]
  88           self.headers['Content-Type'] ||= 'application/json'
  89           self.body = serialize_body(options[:body_object])
  90         else
  91           self.body = ''
  92         end
  93
  94         unless self.api_method
  95           self.http_method = options[:http_method] || 'GET'
  96           self.uri = options[:uri]
  97         end
  98       end
  99
 100       # @!attribute [r] upload_type
 101       # @return [String] protocol used for upload
 102       def upload_type
 103         return self.parameters['uploadType'] || self.parameters['upload_type']
 104       end
 105
 106       # @!attribute http_method
 107       # @return [Symbol] HTTP method if invoking a URI
 108       def http_method
 109         return @http_method ||= self.api_method.http_method.to_s.downcase.to_sym
 110       end
 111
 112       def http_method=(new_http_method)
 113         if new_http_method.kind_of?(Symbol)
 114           @http_method = new_http_method.to_s.downcase.to_sym
 115         elsif new_http_method.respond_to?(:to_str)
 116           @http_method = new_http_method.to_s.downcase.to_sym
 117         else
 118           raise TypeError,
 119             "Expected String or Symbol, got #{new_http_method.class}."
 120         end
 121       end
 122
 123       def api_method=(new_api_method)
 124         if new_api_method.nil? || new_api_method.kind_of?(Google::APIClient::Method)
 125           @api_method = new_api_method
 126         else
 127           raise TypeError,
 128             "Expected Google::APIClient::Method, got #{new_api_method.class}."
 129         end
 130       end
 131
 132       # @!attribute uri
 133       # @return [Addressable::URI] URI to send request
 134       def uri
 135         return @uri ||= self.api_method.generate_uri(self.parameters)
 136       end
 137
 138       def uri=(new_uri)
 139         @uri = Addressable::URI.parse(new_uri)
 140         @parameters.update(@uri.query_values) unless @uri.query_values.nil?
 141       end
 142
 143
 144       # Transmits the request with the given connection
 145       #
 146       # @api private
 147       #
 148       # @param [Faraday::Connection] connection
 149       #   the connection to transmit with
 150       #
 151       # @return [Google::APIClient::Result]
 152       #   result of API request
 153       def send(connection)
 154         http_response = connection.app.call(self.to_env(connection))
 155         result = self.process_http_response(http_response)
 156
 157         # Resumamble slightly different than other upload protocols in that it requires at least
 158         # 2 requests.
 159         if self.upload_type == 'resumable'
 160           upload =  result.resumable_upload
 161           unless upload.complete?
 162             result = upload.send(connection)
 163           end
 164         end
 165         return result
 166       end
 167
 168       # Convert to an HTTP request. Returns components in order of method, URI,
 169       # request headers, and body
 170       #
 171       # @api private
 172       #
 173       # @return [Array<(Symbol, Addressable::URI, Hash, [#read,#to_str])>]
 174       def to_http_request
 175         request = (
 176           if self.uri
 177             unless self.parameters.empty?
 178               self.uri.query = Addressable::URI.form_encode(self.parameters)
 179             end
 180             [self.http_method, self.uri.to_s, self.headers, self.body]
 181           else
 182             self.api_method.generate_request(self.parameters, self.body, self.headers)
 183           end)
 184       end
 185
 186       ##
 187       # Hashified verison of the API request
 188       #
 189       # @return [Hash]
 190       def to_hash
 191         options = {}
 192         if self.api_method
 193           options[:api_method] = self.api_method
 194           options[:parameters] = self.parameters
 195         else
 196           options[:http_method] = self.http_method
 197           options[:uri] = self.uri
 198         end
 199         options[:headers] = self.headers
 200         options[:body] = self.body
 201         options[:media] = self.media
 202         unless self.authorization.nil?
 203           options[:authorization] = self.authorization
 204         end
 205         return options
 206       end
 207
 208       ##
 209       # Prepares the request for execution, building a hash of parts
 210       # suitable for sending to Faraday::Connection.
 211       #
 212       # @api private
 213       #
 214       # @param [Faraday::Connection] connection
 215       #   Connection for building the request
 216       #
 217       # @return [Hash]
 218       #   Encoded request
 219       def to_env(connection)
 220         method, uri, headers, body = self.to_http_request
 221         http_request = connection.build_request(method) do |req|
 222           req.url(uri)
 223           req.headers.update(headers)
 224           req.body = body
 225         end
 226
 227         if self.authorization.respond_to?(:generate_authenticated_request)
 228           http_request = self.authorization.generate_authenticated_request(
 229             :request => http_request,
 230             :connection => connection
 231           )
 232         end
 233
 234         request_env = http_request.to_env(connection)
 235       end
 236
 237       ##
 238       # Convert HTTP response to an API Result
 239       #
 240       # @api private
 241       #
 242       # @param [Faraday::Response] response
 243       #   HTTP response
 244       #
 245       # @return [Google::APIClient::Result]
 246       #   Processed API response
 247       def process_http_response(response)
 248         Result.new(self, response)
 249       end
 250
 251       protected
 252
 253       ##
 254       # Adjust headers & body for media uploads
 255       #
 256       # @api private
 257       #
 258       # @param [Hash] options
 259       # @option options [Hash, Array] :parameters
 260       #   Request parameters for the API method.
 261       # @option options [Google::APIClient::UploadIO] :media
 262       #   File to upload, if media upload request
 263       # @option options [#to_json, #to_hash] :body_object
 264       #   Main body of the API request. Typically hash or object that can
 265       #   be serialized to JSON
 266       # @option options [#read, #to_str] :body
 267       #   Raw body to send in POST/PUT requests
 268       def initialize_media_upload(options)
 269         self.media = options[:media]
 270         case self.upload_type
 271         when "media"
 272           if options[:body] || options[:body_object]
 273             raise ArgumentError, "Can not specify body & body object for simple uploads"
 274           end
 275           self.headers['Content-Type'] ||= self.media.content_type
 276           self.body = self.media
 277         when "multipart"
 278           unless options[:body_object]
 279             raise ArgumentError, "Multipart requested but no body object"
 280           end
 281           metadata = StringIO.new(serialize_body(options[:body_object]))
 282           build_multipart([Faraday::UploadIO.new(metadata, 'application/json', 'file.json'), self.media])
 283         when "resumable"
 284           file_length = self.media.length
 285           self.headers['X-Upload-Content-Type'] = self.media.content_type
 286           self.headers['X-Upload-Content-Length'] = file_length.to_s
 287           if options[:body_object]
 288             self.headers['Content-Type'] ||= 'application/json'
 289             self.body = serialize_body(options[:body_object])
 290           else
 291             self.body = ''
 292           end
 293         end
 294       end
 295
 296       ##
 297       # Assemble a multipart message from a set of parts
 298       #
 299       # @api private
 300       #
 301       # @param [Array<[#read,#to_str]>] parts
 302       #   Array of parts to encode.
 303       # @param [String] mime_type
 304       #   MIME type of the message
 305       # @param [String] boundary
 306       #   Boundary for separating each part of the message
 307       def build_multipart(parts, mime_type = 'multipart/related', boundary = MULTIPART_BOUNDARY)
 308         env = {
 309           :request_headers => {'Content-Type' => "#{mime_type};boundary=#{boundary}"},
 310           :request => { :boundary => boundary }
 311         }
 312         multipart = Faraday::Request::Multipart.new
 313         self.body = multipart.create_multipart(env, parts.map {|part| [nil, part]})
 314         self.headers.update(env[:request_headers])
 315       end
 316
 317       ##
 318       # Serialize body object to JSON
 319       #
 320       # @api private
 321       #
 322       # @param [#to_json,#to_hash] body
 323       #   object to serialize
 324       #
 325       # @return [String]
 326       #   JSON
 327       def serialize_body(body)
 328         return body.to_json if body.respond_to?(:to_json)
 329         return MultiJson.dump(options[:body_object].to_hash) if body.respond_to?(:to_hash)
 330         raise TypeError, 'Could not convert body object to JSON.' +
 331                          'Must respond to :to_json or :to_hash.'
 332       end
 333
 334     end
 335
 336     ##
 337     # Subclass of Request for backwards compatibility with pre-0.5.0 versions of the library
 338     #
 339     # @deprecated
 340     #   use {Google::APIClient::Request} instead
 341     class Reference < Request
 342     end
 343   end
 344 end