1 # Copyright 2010 Google Inc.
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
7 # http://www.apache.org/licenses/LICENSE-2.0
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.
16 require 'addressable/uri'
18 require 'google/inflection'
19 require 'google/api_client/discovery/resource'
20 require 'google/api_client/discovery/method'
21 require 'google/api_client/discovery/media'
26 # A service that has been described by a discovery document.
30 # Creates a description of a particular version of a service.
32 # @param [String] document_base
33 # Base URI for the service
34 # @param [Hash] discovery_document
35 # The section of the discovery document that applies to this service
38 # @return [Google::APIClient::API] The constructed service object.
39 def initialize(document_base, discovery_document)
40 @document_base = Addressable::URI.parse(document_base)
41 @discovery_document = discovery_document
42 metaclass = (class << self; self; end)
43 self.discovered_resources.each do |resource|
44 method_name = Google::INFLECTOR.underscore(resource.name).to_sym
45 if !self.respond_to?(method_name)
46 metaclass.send(:define_method, method_name) { resource }
49 self.discovered_methods.each do |method|
50 method_name = Google::INFLECTOR.underscore(method.name).to_sym
51 if !self.respond_to?(method_name)
52 metaclass.send(:define_method, method_name) { method }
58 # Returns the id of the service.
60 # @return [String] The service id.
63 @discovery_document['id'] ||
64 "#{self.name}:#{self.version}"
69 # Returns the identifier for the service.
71 # @return [String] The service identifier.
73 return @discovery_document['name']
77 # Returns the version of the service.
79 # @return [String] The service version.
81 return @discovery_document['version']
85 # Returns a human-readable title for the API.
87 # @return [Hash] The API title.
89 return @discovery_document['title']
93 # Returns a human-readable description of the API.
95 # @return [Hash] The API description.
97 return @discovery_document['description']
101 # Returns a URI for the API documentation.
103 # @return [Hash] The API documentation.
105 return Addressable::URI.parse(@discovery_document['documentationLink'])
109 # Returns true if this is the preferred version of this API.
111 # @return [TrueClass, FalseClass]
112 # Whether or not this is the preferred version of this API.
114 return !!@discovery_document['preferred']
118 # Returns the list of API features.
121 # The features supported by this API.
123 return @discovery_document['features'] || []
127 # Returns true if this API uses a data wrapper.
129 # @return [TrueClass, FalseClass]
130 # Whether or not this API uses a data wrapper.
132 return self.features.include?('dataWrapper')
136 # Returns the base URI for the discovery document.
138 # @return [Addressable::URI] The base URI.
139 attr_reader :document_base
142 # Returns the base URI for this version of the service.
144 # @return [Addressable::URI] The base URI that methods are joined to.
146 if @discovery_document['basePath']
147 return @method_base ||= (
148 self.document_base.join(Addressable::URI.parse(@discovery_document['basePath']))
156 # Updates the hierarchy of resources and methods with the new base.
158 # @param [Addressable::URI, #to_str, String] new_method_base
159 # The new base URI to use for the service.
160 def method_base=(new_method_base)
161 @method_base = Addressable::URI.parse(new_method_base)
162 self.discovered_resources.each do |resource|
163 resource.method_base = @method_base
165 self.discovered_methods.each do |method|
166 method.method_base = @method_base
171 # Returns the base URI for batch calls to this service.
173 # @return [Addressable::URI] The base URI that methods are joined to.
175 if @discovery_document['batchPath']
176 return @batch_path ||= (
177 self.document_base.join(Addressable::URI.parse('/' +
178 @discovery_document['batchPath']))
186 # A list of schemas available for this version of the API.
188 # @return [Hash] A list of {Google::APIClient::Schema} objects.
190 return @schemas ||= (
191 (@discovery_document['schemas'] || []).inject({}) do |accu, (k, v)|
192 accu[k] = Google::APIClient::Schema.parse(self, v)
199 # Returns a schema for a kind value.
201 # @return [Google::APIClient::Schema] The associated Schema object.
202 def schema_for_kind(kind)
203 api_name, schema_name = kind.split('#', 2)
204 if api_name != self.name
206 "The kind does not match this API. " +
207 "Expected '#{self.name}', got '#{api_name}'."
209 for k, v in self.schemas
210 return v if k.downcase == schema_name.downcase
216 # A list of resources available at the root level of this version of the
219 # @return [Array] A list of {Google::APIClient::Resource} objects.
220 def discovered_resources
221 return @discovered_resources ||= (
222 (@discovery_document['resources'] || []).inject([]) do |accu, (k, v)|
223 accu << Google::APIClient::Resource.new(
224 self, self.method_base, k, v
232 # A list of methods available at the root level of this version of the
235 # @return [Array] A list of {Google::APIClient::Method} objects.
236 def discovered_methods
237 return @discovered_methods ||= (
238 (@discovery_document['methods'] || []).inject([]) do |accu, (k, v)|
239 accu << Google::APIClient::Method.new(self, self.method_base, k, v)
246 # Allows deep inspection of the discovery document.
248 return @discovery_document[key]
252 # Converts the service to a flat mapping of RPC names and method objects.
254 # @return [Hash] All methods available on the service.
257 # # Discover available methods
258 # method_names = client.discovered_api('buzz').to_h.keys
260 return @hash ||= (begin
262 self.discovered_methods.each do |method|
263 methods_hash[method.id] = method
265 self.discovered_resources.each do |resource|
266 methods_hash.merge!(resource.to_h)
273 # Returns a <code>String</code> representation of the service's state.
275 # @return [String] The service's state, as a <code>String</code>.
278 "#<%s:%#0x ID:%s>", self.class.to_s, self.object_id, self.id