Merge branch 'main' from workbench2.git
[arvados.git] / sdk / ruby-google-api-client / lib / google / api_client / discovery / method.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
16 require 'addressable/uri'
17 require 'addressable/template'
18
19 require 'google/api_client/errors'
20
21
22 module Google
23   class APIClient
24     ##
25     # A method that has been described by a discovery document.
26     class Method
27
28       ##
29       # Creates a description of a particular method.
30       #
31       # @param [Google::APIClient::API] api
32       #   The API this method belongs to.
33       # @param [Addressable::URI] method_base
34       #   The base URI for the service.
35       # @param [String] method_name
36       #   The identifier for the method.
37       # @param [Hash] discovery_document
38       #   The section of the discovery document that applies to this method.
39       #
40       # @return [Google::APIClient::Method] The constructed method object.
41       def initialize(api, method_base, method_name, discovery_document)
42         @api = api
43         @method_base = method_base
44         @name = method_name
45         @discovery_document = discovery_document
46       end
47
48       # @return [String] unparsed discovery document for the method
49       attr_reader :discovery_document
50
51       ##
52       # Returns the API this method belongs to.
53       #
54       # @return [Google::APIClient::API] The API this method belongs to.
55       attr_reader :api
56
57       ##
58       # Returns the identifier for the method.
59       #
60       # @return [String] The method identifier.
61       attr_reader :name
62
63       ##
64       # Returns the base URI for the method.
65       #
66       # @return [Addressable::URI]
67       #   The base URI that this method will be joined to.
68       attr_reader :method_base
69
70       ##
71       # Updates the method with the new base.
72       #
73       # @param [Addressable::URI, #to_str, String] new_method_base
74       #   The new base URI to use for the method.
75       def method_base=(new_method_base)
76         @method_base = Addressable::URI.parse(new_method_base)
77         @uri_template = nil
78       end
79
80       ##
81       # Returns a human-readable description of the method.
82       #
83       # @return [Hash] The API description.
84       def description
85         return @discovery_document['description']
86       end
87       
88       ##
89       # Returns the method ID.
90       #
91       # @return [String] The method identifier.
92       def id
93         return @discovery_document['id']
94       end
95
96       ##
97       # Returns the HTTP method or 'GET' if none is specified.
98       #
99       # @return [String] The HTTP method that will be used in the request.
100       def http_method
101         return @discovery_document['httpMethod'] || 'GET'
102       end
103
104       ##
105       # Returns the URI template for the method.  A parameter list can be
106       # used to expand this into a URI.
107       #
108       # @return [Addressable::Template] The URI template.
109       def uri_template
110         return @uri_template ||= Addressable::Template.new(
111           self.method_base.join(Addressable::URI.parse("./" + @discovery_document['path']))
112         )
113       end
114
115       ##
116       # Returns media upload information for this method, if supported
117       #
118       # @return [Google::APIClient::MediaUpload] Description of upload endpoints
119       def media_upload
120         if @discovery_document['mediaUpload']
121           return @media_upload ||= Google::APIClient::MediaUpload.new(self, self.method_base, @discovery_document['mediaUpload'])
122         else
123           return nil
124         end
125       end
126
127       ##
128       # Returns the Schema object for the method's request, if any.
129       #
130       # @return [Google::APIClient::Schema] The request schema.
131       def request_schema
132         if @discovery_document['request']
133           schema_name = @discovery_document['request']['$ref']
134           return @api.schemas[schema_name]
135         else
136           return nil
137         end
138       end
139
140       ##
141       # Returns the Schema object for the method's response, if any.
142       #
143       # @return [Google::APIClient::Schema] The response schema.
144       def response_schema
145         if @discovery_document['response']
146           schema_name = @discovery_document['response']['$ref']
147           return @api.schemas[schema_name]
148         else
149           return nil
150         end
151       end
152
153       ##
154       # Normalizes parameters, converting to the appropriate types.
155       #
156       # @param [Hash, Array] parameters
157       #   The parameters to normalize.
158       #
159       # @return [Hash] The normalized parameters.
160       def normalize_parameters(parameters={})
161         # Convert keys to Strings when appropriate
162         if parameters.kind_of?(Hash) || parameters.kind_of?(Array)
163           # Returning an array since parameters can be repeated (ie, Adsense Management API)
164           parameters = parameters.inject([]) do |accu, (k, v)|
165             k = k.to_s if k.kind_of?(Symbol)
166             k = k.to_str if k.respond_to?(:to_str)
167             unless k.kind_of?(String)
168               raise TypeError, "Expected String, got #{k.class}."
169             end
170             accu << [k, v]
171             accu
172           end
173         else
174           raise TypeError,
175             "Expected Hash or Array, got #{parameters.class}."
176         end
177         return parameters
178       end
179
180       ##
181       # Expands the method's URI template using a parameter list.
182       #
183       # @api private
184       # @param [Hash, Array] parameters
185       #   The parameter list to use.
186       #
187       # @return [Addressable::URI] The URI after expansion.
188       def generate_uri(parameters={})
189         parameters = self.normalize_parameters(parameters)
190         
191         self.validate_parameters(parameters)
192         template_variables = self.uri_template.variables
193         upload_type = parameters.assoc('uploadType') || parameters.assoc('upload_type')
194         if upload_type
195           unless self.media_upload
196             raise ArgumentException, "Media upload not supported for this method"
197           end
198           case upload_type.last
199           when 'media', 'multipart', 'resumable'
200             uri = self.media_upload.uri_template.expand(parameters)
201           else
202             raise ArgumentException, "Invalid uploadType '#{upload_type}'"
203           end
204         else
205           uri = self.uri_template.expand(parameters)
206         end
207         query_parameters = parameters.reject do |k, v|
208           template_variables.include?(k)
209         end
210         # encode all non-template parameters
211         params = ""
212         unless query_parameters.empty?
213           params = "?" + Addressable::URI.form_encode(query_parameters.sort)
214         end
215         # Normalization is necessary because of undesirable percent-escaping
216         # during URI template expansion
217         return uri.normalize + params
218       end
219
220       ##
221       # Generates an HTTP request for this method.
222       #
223       # @api private
224       # @param [Hash, Array] parameters
225       #   The parameters to send.
226       # @param [String, StringIO] body The body for the HTTP request.
227       # @param [Hash, Array] headers The HTTP headers for the request.
228       # @option options [Faraday::Connection] :connection
229       #   The HTTP connection to use.
230       #
231       # @return [Array] The generated HTTP request.
232       def generate_request(parameters={}, body='', headers={}, options={})
233         if !headers.kind_of?(Array) && !headers.kind_of?(Hash)
234           raise TypeError, "Expected Hash or Array, got #{headers.class}."
235         end
236         method = self.http_method.to_s.downcase.to_sym
237         uri = self.generate_uri(parameters)
238         headers = Faraday::Utils::Headers.new(headers)
239         return [method, uri, headers, body]
240       end
241
242
243       ##
244       # Returns a <code>Hash</code> of the parameter descriptions for
245       # this method.
246       #
247       # @return [Hash] The parameter descriptions.
248       def parameter_descriptions
249         @parameter_descriptions ||= (
250           @discovery_document['parameters'] || {}
251         ).inject({}) { |h,(k,v)| h[k]=v; h }
252       end
253
254       ##
255       # Returns an <code>Array</code> of the parameters for this method.
256       #
257       # @return [Array] The parameters.
258       def parameters
259         @parameters ||= ((
260           @discovery_document['parameters'] || {}
261         ).inject({}) { |h,(k,v)| h[k]=v; h }).keys
262       end
263
264       ##
265       # Returns an <code>Array</code> of the required parameters for this
266       # method.
267       #
268       # @return [Array] The required parameters.
269       #
270       # @example
271       #   # A list of all required parameters.
272       #   method.required_parameters
273       def required_parameters
274         @required_parameters ||= ((self.parameter_descriptions.select do |k, v|
275           v['required']
276         end).inject({}) { |h,(k,v)| h[k]=v; h }).keys
277       end
278
279       ##
280       # Returns an <code>Array</code> of the optional parameters for this
281       # method.
282       #
283       # @return [Array] The optional parameters.
284       #
285       # @example
286       #   # A list of all optional parameters.
287       #   method.optional_parameters
288       def optional_parameters
289         @optional_parameters ||= ((self.parameter_descriptions.reject do |k, v|
290           v['required']
291         end).inject({}) { |h,(k,v)| h[k]=v; h }).keys
292       end
293
294       ##
295       # Verifies that the parameters are valid for this method.  Raises an
296       # exception if validation fails.
297       #
298       # @api private
299       # @param [Hash, Array] parameters
300       #   The parameters to verify.
301       #
302       # @return [NilClass] <code>nil</code> if validation passes.
303       def validate_parameters(parameters={})
304         parameters = self.normalize_parameters(parameters)
305         required_variables = ((self.parameter_descriptions.select do |k, v|
306           v['required']
307         end).inject({}) { |h,(k,v)| h[k]=v; h }).keys
308         missing_variables = required_variables - parameters.map { |(k, _)| k }
309         if missing_variables.size > 0
310           raise ArgumentError,
311             "Missing required parameters: #{missing_variables.join(', ')}."
312         end
313         parameters.each do |k, v|
314           # Handle repeated parameters.
315           if self.parameter_descriptions[k] &&
316               self.parameter_descriptions[k]['repeated'] &&
317               v.kind_of?(Array)
318             # If this is a repeated parameter and we've got an array as a
319             # value, just provide the whole array to the loop below.
320             items = v
321           else
322             # If this is not a repeated parameter, or if it is but we're
323             # being given a single value, wrap the value in an array, so that
324             # the loop below still works for the single element.
325             items = [v]
326           end
327
328           items.each do |item|
329             if self.parameter_descriptions[k]
330               enum = self.parameter_descriptions[k]['enum']
331               if enum && !enum.include?(item)
332                 raise ArgumentError,
333                   "Parameter '#{k}' has an invalid value: #{item}. " +
334                   "Must be one of #{enum.inspect}."
335               end
336               pattern = self.parameter_descriptions[k]['pattern']
337               if pattern
338                 regexp = Regexp.new("^#{pattern}$")
339                 if item !~ regexp
340                   raise ArgumentError,
341                     "Parameter '#{k}' has an invalid value: #{item}. " +
342                     "Must match: /^#{pattern}$/."
343                 end
344               end
345             end
346           end
347         end
348         return nil
349       end
350
351       ##
352       # Returns a <code>String</code> representation of the method's state.
353       #
354       # @return [String] The method's state, as a <code>String</code>.
355       def inspect
356         sprintf(
357           "#<%s:%#0x ID:%s>",
358           self.class.to_s, self.object_id, self.id
359         )
360       end
361     end
362   end
363 end