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

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:

  • api (String) —

    The identifier for the service. Note that while this frequently matches the first segment of all of the service’s RPC names, this should not be assumed. There is no requirement that these match.

  • version (String) —

    The identifier for the service version.

  • api_description (Hash) —

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



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/google/api_client/discovery/api.rb', line 43

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 = Google::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 = Google::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

#document_base ⇒ Addressable::URI (readonly)

Returns the base URI for the discovery document.

Returns:

  • (Addressable::URI) —

    The base URI.



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

def document_base
  @document_base
end

Instance Method Details

#[](key) ⇒ Object

Allows deep inspection of the discovery document.



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

def [](key)
  return @discovery_document[key]
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.



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

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.



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

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

#description ⇒ Hash

Returns a human-readable description of the API.

Returns:

  • (Hash) —

    The API description.



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

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.



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

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.



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

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.



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

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.



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

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

#id ⇒ String

Returns the id of the service.

Returns:

  • (String) —

    The service id.



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

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.



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

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.



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

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_base (Addressable::URI, #to_str, String) —

    The new base URI to use for the service.



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

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.



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

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.



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

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

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

Returns a schema for a kind value.

Returns:



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

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.



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

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.



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

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.



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

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.



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

def version
  return @discovery_document['version']
end