Class: Google::APIClient::API

Inherits:
Object
  • Object
show all
Defined in:
lib/google/api_client/discovery/api.rb

Overview

A service that has been described by a discovery document.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document_base, discovery_document) ⇒ Google::APIClient::API

Creates a description of a particular version of a service.

Parameters:

  • document_base (String) —

    Base URI for the service

  • discovery_document (Hash) —

    The section of the discovery document that applies to this service version.



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/google/api_client/discovery/api.rb', line 39

def initialize(document_base, discovery_document)
  @document_base = Addressable::URI.parse(document_base)
  @discovery_document = discovery_document
  metaclass = (class << self; self; end)
  self.discovered_resources.each do |resource|
    method_name = ActiveSupport::Inflector.underscore(resource.name).to_sym
    if !self.respond_to?(method_name)
      metaclass.send(:define_method, method_name) { resource }
    end
  end
  self.discovered_methods.each do |method|
    method_name = ActiveSupport::Inflector.underscore(method.name).to_sym
    if !self.respond_to?(method_name)
      metaclass.send(:define_method, method_name) { method }
    end
  end
end

Instance Attribute Details

#discovery_document ⇒ String (readonly)

Returns unparsed discovery document for the API

Returns:

  • (String) —

    unparsed discovery document for the API



58
59
60
 
# File 'lib/google/api_client/discovery/api.rb', line 58

def discovery_document
  @discovery_document
end

#document_base ⇒ Addressable::URI (readonly)

Returns the base URI for the discovery document.

Returns:

  • (Addressable::URI) —

    The base URI.



142
143
144
 
# File 'lib/google/api_client/discovery/api.rb', line 142

def document_base
  @document_base
end

Class Method Details

._load(obj) ⇒ Object

Marshalling support - Restore an API instance from serialized form



294
295
296
 
# File 'lib/google/api_client/discovery/api.rb', line 294

def self._load(obj)
  new(*MultiJson.load(obj)) 
end

Instance Method Details

#[](key) ⇒ Object

Allows deep inspection of the discovery document.



250
251
252
 
# File 'lib/google/api_client/discovery/api.rb', line 250

def [](key)
  return @discovery_document[key]
end

#_dump(level) ⇒ Object

Marshalling support - serialize the API to a string (doc base + original discovery document).



288
289
290
 
# File 'lib/google/api_client/discovery/api.rb', line 288

def _dump(level)
  MultiJson.dump([@document_base.to_s, @discovery_document])
end

#batch_path ⇒ Addressable::URI

Returns the base URI for batch calls to this service.

Returns:

  • (Addressable::URI) —

    The base URI that methods are joined to.



177
178
179
180
181
182
183
184
185
186
 
# File 'lib/google/api_client/discovery/api.rb', line 177

def batch_path
  if @discovery_document['batchPath']
    return @batch_path ||= (
      self.document_base.join(Addressable::URI.parse('/' +
          @discovery_document['batchPath']))
    ).normalize
  else
    return nil
  end
end

#data_wrapper? ⇒ TrueClass, FalseClass

Returns true if this API uses a data wrapper.

Returns:

  • (TrueClass, FalseClass) —

    Whether or not this API uses a data wrapper.



134
135
136
 
# File 'lib/google/api_client/discovery/api.rb', line 134

def data_wrapper?
  return self.features.include?('dataWrapper')
end

#description ⇒ Hash

Returns a human-readable description of the API.

Returns:

  • (Hash) —

    The API description.



99
100
101
 
# File 'lib/google/api_client/discovery/api.rb', line 99

def description
  return @discovery_document['description']
end

#discovered_methods ⇒ Array

A list of methods available at the root level of this version of the API.

Returns:

  • (Array) —

    A list of Method objects.



239
240
241
242
243
244
245
246
 
# File 'lib/google/api_client/discovery/api.rb', line 239

def discovered_methods
  return @discovered_methods ||= (
    (@discovery_document['methods'] || []).inject([]) do |accu, (k, v)|
      accu << Google::APIClient::Method.new(self, self.method_base, k, v)
      accu
    end
  )
end

#discovered_resources ⇒ Array

A list of resources available at the root level of this version of the API.

Returns:

  • (Array) —

    A list of Resource objects.



223
224
225
226
227
228
229
230
231
232
 
# File 'lib/google/api_client/discovery/api.rb', line 223

def discovered_resources
  return @discovered_resources ||= (
    (@discovery_document['resources'] || []).inject([]) do |accu, (k, v)|
      accu << Google::APIClient::Resource.new(
        self, self.method_base, k, v
      )
      accu
    end
  )
end

#documentation ⇒ Hash

Returns a URI for the API documentation.

Returns:

  • (Hash) —

    The API documentation.



107
108
109
 
# File 'lib/google/api_client/discovery/api.rb', line 107

def documentation
  return Addressable::URI.parse(@discovery_document['documentationLink'])
end

#features ⇒ Array

Returns the list of API features.

Returns:

  • (Array) —

    The features supported by this API.



125
126
127
 
# File 'lib/google/api_client/discovery/api.rb', line 125

def features
  return @discovery_document['features'] || []
end

#id ⇒ String

Returns the id of the service.

Returns:

  • (String) —

    The service id.



64
65
66
67
68
69
 
# File 'lib/google/api_client/discovery/api.rb', line 64

def id
  return (
    @discovery_document['id'] ||
    "#{self.name}:#{self.version}"
  )
end

#inspect ⇒ String

Returns a String representation of the service's state.

Returns:

  • (String) —

    The service's state, as a String.



279
280
281
282
283
 
# File 'lib/google/api_client/discovery/api.rb', line 279

def inspect
  sprintf(
    "#<%s:%#0x ID:%s>", self.class.to_s, self.object_id, self.id
  )
end

#method_base ⇒ Addressable::URI

Returns the base URI for this version of the service.

Returns:

  • (Addressable::URI) —

    The base URI that methods are joined to.



148
149
150
151
152
153
154
155
156
 
# File 'lib/google/api_client/discovery/api.rb', line 148

def method_base
  if @discovery_document['basePath']
    return @method_base ||= (
      self.document_base.join(Addressable::URI.parse(@discovery_document['basePath']))
    ).normalize
  else
    return nil
  end
end

#method_base=(new_method_base) ⇒ Object

Updates the hierarchy of resources and methods with the new base.

Parameters:

  • new_method_base (Addressable::URI, #to_str, String) —

    The new base URI to use for the service.



163
164
165
166
167
168
169
170
171
 
# File 'lib/google/api_client/discovery/api.rb', line 163

def method_base=(new_method_base)
  @method_base = Addressable::URI.parse(new_method_base)
  self.discovered_resources.each do |resource|
    resource.method_base = @method_base
  end
  self.discovered_methods.each do |method|
    method.method_base = @method_base
  end
end

#name ⇒ String

Returns the identifier for the service.

Returns:

  • (String) —

    The service identifier.



75
76
77
 
# File 'lib/google/api_client/discovery/api.rb', line 75

def name
  return @discovery_document['name']
end

#preferred ⇒ TrueClass, FalseClass

Returns true if this is the preferred version of this API.

Returns:

  • (TrueClass, FalseClass) —

    Whether or not this is the preferred version of this API.



116
117
118
 
# File 'lib/google/api_client/discovery/api.rb', line 116

def preferred
  return !!@discovery_document['preferred']
end

#schema_for_kind(kind) ⇒ Google::APIClient::Schema

Returns a schema for a kind value.

Returns:



205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/google/api_client/discovery/api.rb', line 205

def schema_for_kind(kind)
  api_name, schema_name = kind.split('#', 2)
  if api_name != self.name
    raise ArgumentError,
      "The kind does not match this API. " +
      "Expected '#{self.name}', got '#{api_name}'."
  end
  for k, v in self.schemas
    return v if k.downcase == schema_name.downcase
  end
  return nil
end

#schemas ⇒ Hash

A list of schemas available for this version of the API.

Returns:

  • (Hash) —

    A list of Schema objects.



192
193
194
195
196
197
198
199
 
# File 'lib/google/api_client/discovery/api.rb', line 192

def schemas
  return @schemas ||= (
    (@discovery_document['schemas'] || []).inject({}) do |accu, (k, v)|
      accu[k] = Google::APIClient::Schema.parse(self, v)
      accu
    end
  )
end

#title ⇒ Hash

Returns a human-readable title for the API.

Returns:

  • (Hash) —

    The API title.



91
92
93
 
# File 'lib/google/api_client/discovery/api.rb', line 91

def title
  return @discovery_document['title']
end

#to_h ⇒ Hash

Converts the service to a flat mapping of RPC names and method objects.

Examples:

# Discover available methods
method_names = client.discovered_api('buzz').to_h.keys

Returns:

  • (Hash) —

    All methods available on the service.



262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/google/api_client/discovery/api.rb', line 262

def to_h
  return @hash ||= (begin
    methods_hash = {}
    self.discovered_methods.each do |method|
      methods_hash[method.id] = method
    end
    self.discovered_resources.each do |resource|
      methods_hash.merge!(resource.to_h)
    end
    methods_hash
  end)
end

#version ⇒ String

Returns the version of the service.

Returns:

  • (String) —

    The service version.



83
84
85
 
# File 'lib/google/api_client/discovery/api.rb', line 83

def version
  return @discovery_document['version']
end