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       attr_reader :parameters, :headers, :api_method
  32       attr_accessor :connection, :media, :authorization, :authenticated, :body
  33
  34       ##
  35       # Build a request
  36       #
  37       # @param [Hash] options
  38       # @option options [Hash, Array] :parameters
  39       #   Request parameters for the API method.
  40       # @option options [Google::APIClient::Method] :api_method
  41       #   API method to invoke. Either :api_method or :uri must be specified
  42       # @option options [TrueClass, FalseClass] :authenticated
  43       #   True if request should include credentials. Implicitly true if
  44       #   unspecified and :authorization present
  45       # @option options [#generate_signed_request] :authorization
  46       #   OAuth credentials
  47       # @option options [Google::APIClient::UploadIO] :media
  48       #   File to upload, if media upload request
  49       # @option options [#to_json, #to_hash] :body_object
  50       #   Main body of the API request. Typically hash or object that can
  51       #   be serialized to JSON
  52       # @option options [#read, #to_str] :body
  53       #   Raw body to send in POST/PUT requests
  54       # @option options [String, Addressable::URI] :uri
  55       #   URI to request. Either :api_method or :uri must be specified
  56       # @option options [String, Symbol] :http_method
  57       #   HTTP method when requesting a URI
  58       def initialize(options={})
  59         @parameters = Hash[options[:parameters] || {}]
  60         @headers = Faraday::Utils::Headers.new
  61         self.headers.merge!(options[:headers]) unless options[:headers].nil?
  62         self.api_method = options[:api_method]
  63         self.authenticated = options[:authenticated]
  64         self.authorization = options[:authorization]
  65
  66         # These parameters are handled differently because they're not
  67         # parameters to the API method, but rather to the API system.
  68         self.parameters['key'] ||= options[:key] if options[:key]
  69         self.parameters['userIp'] ||= options[:user_ip] if options[:user_ip]
  70
  71         if options[:media]
  72           self.initialize_media_upload(options)
  73         elsif options[:body]
  74           self.body = options[:body]
  75         elsif options[:body_object]
  76           self.headers['Content-Type'] ||= 'application/json'
  77           self.body = serialize_body(options[:body_object])
  78         else
  79           self.body = ''
  80         end
  81
  82         unless self.api_method
  83           self.http_method = options[:http_method] || 'GET'
  84           self.uri = options[:uri]
  85         end
  86       end
  87
  88       def upload_type
  89         return self.parameters['uploadType'] || self.parameters['upload_type']
  90       end
  91
  92       def http_method
  93         return @http_method ||= self.api_method.http_method.to_s.downcase.to_sym
  94       end
  95
  96       def http_method=(new_http_method)
  97         if new_http_method.kind_of?(Symbol)
  98           @http_method = new_http_method.to_s.downcase.to_sym
  99         elsif new_http_method.respond_to?(:to_str)
 100           @http_method = new_http_method.to_s.downcase.to_sym
 101         else
 102           raise TypeError,
 103             "Expected String or Symbol, got #{new_http_method.class}."
 104         end
 105       end
 106
 107       def api_method=(new_api_method)
 108         if new_api_method.nil? || new_api_method.kind_of?(Google::APIClient::Method)
 109           @api_method = new_api_method
 110         else
 111           raise TypeError,
 112             "Expected Google::APIClient::Method, got #{new_api_method.class}."
 113         end
 114       end
 115
 116       def uri
 117         return @uri ||= self.api_method.generate_uri(self.parameters)
 118       end
 119
 120       def uri=(new_uri)
 121         @uri = Addressable::URI.parse(new_uri)
 122         @parameters.update(@uri.query_values) unless @uri.query_values.nil?
 123       end
 124
 125       # Transmits the request with the given connection
 126       #
 127       # @api private
 128       #
 129       # @param [Faraday::Connection] connection
 130       #   the connection to transmit with
 131       #
 132       # @return [Google::APIClient::Result]
 133       #   result of API request
 134       def send(connection)
 135         http_response = connection.app.call(self.to_env(connection))
 136         result = self.process_http_response(http_response)
 137
 138         # Resumamble slightly different than other upload protocols in that it requires at least
 139         # 2 requests.
 140         if self.upload_type == 'resumable'
 141           upload =  result.resumable_upload
 142           unless upload.complete?
 143             result = upload.send(connection)
 144           end
 145         end
 146         return result
 147       end
 148
 149       # Convert to an HTTP request. Returns components in order of method, URI,
 150       # request headers, and body
 151       #
 152       # @api private
 153       #
 154       # @return [Array<(Symbol, Addressable::URI, Hash, [#read,#to_str])>]
 155       def to_http_request
 156         request = (
 157           if self.uri
 158             unless self.parameters.empty?
 159               self.uri.query = Addressable::URI.form_encode(self.parameters)
 160             end
 161             [self.http_method, self.uri.to_s, self.headers, self.body]
 162           else
 163             self.api_method.generate_request(self.parameters, self.body, self.headers)
 164           end)
 165       end
 166
 167       ##
 168       # Hashified verison of the API request
 169       #
 170       # @return [Hash]
 171       def to_hash
 172         options = {}
 173         if self.api_method
 174           options[:api_method] = self.api_method
 175           options[:parameters] = self.parameters
 176         else
 177           options[:http_method] = self.http_method
 178           options[:uri] = self.uri
 179         end
 180         options[:headers] = self.headers
 181         options[:body] = self.body
 182         options[:media] = self.media
 183         unless self.authorization.nil?
 184           options[:authorization] = self.authorization
 185         end
 186         return options
 187       end
 188
 189       ##
 190       # Prepares the request for execution, building a hash of parts
 191       # suitable for sending to Faraday::Connection.
 192       #
 193       # @api private
 194       #
 195       # @param [Faraday::Connection] connection
 196       #   Connection for building the request
 197       #
 198       # @return [Hash]
 199       #   Encoded request
 200       def to_env(connection)
 201         method, uri, headers, body = self.to_http_request
 202         http_request = connection.build_request(method) do |req|
 203           req.url(uri)
 204           req.headers.update(headers)
 205           req.body = body
 206         end
 207
 208         if self.authorization.respond_to?(:generate_authenticated_request)
 209           http_request = self.authorization.generate_authenticated_request(
 210             :request => http_request,
 211             :connection => connection
 212           )
 213         end
 214
 215         request_env = http_request.to_env(connection)
 216       end
 217
 218       ##
 219       # Convert HTTP response to an API Result
 220       #
 221       # @api private
 222       #
 223       # @param [Faraday::Response] response
 224       #   HTTP response
 225       #
 226       # @return [Google::APIClient::Result]
 227       #   Processed API response
 228       def process_http_response(response)
 229         Result.new(self, response)
 230       end
 231
 232       protected
 233
 234       ##
 235       # Adjust headers & body for media uploads
 236       #
 237       # @api private
 238       #
 239       # @param [Hash] options
 240       # @option options [Hash, Array] :parameters
 241       #   Request parameters for the API method.
 242       # @option options [Google::APIClient::UploadIO] :media
 243       #   File to upload, if media upload request
 244       # @option options [#to_json, #to_hash] :body_object
 245       #   Main body of the API request. Typically hash or object that can
 246       #   be serialized to JSON
 247       # @option options [#read, #to_str] :body
 248       #   Raw body to send in POST/PUT requests
 249       def initialize_media_upload(options)
 250         self.media = options[:media]
 251         case self.upload_type
 252         when "media"
 253           if options[:body] || options[:body_object]
 254             raise ArgumentError, "Can not specify body & body object for simple uploads"
 255           end
 256           self.headers['Content-Type'] ||= self.media.content_type
 257           self.body = self.media
 258         when "multipart"
 259           unless options[:body_object]
 260             raise ArgumentError, "Multipart requested but no body object"
 261           end
 262           metadata = StringIO.new(serialize_body(options[:body_object]))
 263           build_multipart([Faraday::UploadIO.new(metadata, 'application/json', 'file.json'), self.media])
 264         when "resumable"
 265           file_length = self.media.length
 266           self.headers['X-Upload-Content-Type'] = self.media.content_type
 267           self.headers['X-Upload-Content-Length'] = file_length.to_s
 268           if options[:body_object]
 269             self.headers['Content-Type'] ||= 'application/json'
 270             self.body = serialize_body(options[:body_object])
 271           else
 272             self.body = ''
 273           end
 274         end
 275       end
 276
 277       ##
 278       # Assemble a multipart message from a set of parts
 279       #
 280       # @api private
 281       #
 282       # @param [Array<[#read,#to_str]>] parts
 283       #   Array of parts to encode.
 284       # @param [String] mime_type
 285       #   MIME type of the message
 286       # @param [String] boundary
 287       #   Boundary for separating each part of the message
 288       def build_multipart(parts, mime_type = 'multipart/related', boundary = MULTIPART_BOUNDARY)
 289         env = {
 290           :request_headers => {'Content-Type' => "#{mime_type};boundary=#{boundary}"},
 291           :request => { :boundary => boundary }
 292         }
 293         multipart = Faraday::Request::Multipart.new
 294         self.body = multipart.create_multipart(env, parts.map {|part| [nil, part]})
 295         self.headers.update(env[:request_headers])
 296       end
 297
 298       ##
 299       # Serialize body object to JSON
 300       #
 301       # @api private
 302       #
 303       # @param [#to_json,#to_hash] body
 304       #   object to serialize
 305       #
 306       # @return [String]
 307       #   JSON
 308       def serialize_body(body)
 309         return body.to_json if body.respond_to?(:to_json)
 310         return MultiJson.dump(options[:body_object].to_hash) if body.respond_to?(:to_hash)
 311         raise TypeError, 'Could not convert body object to JSON.' +
 312                          'Must respond to :to_json or :to_hash.'
 313       end
 314
 315     end
 316
 317     class Reference < Request
 318     end
 319   end
 320 end