Class: Bubbles::Endpoint

Inherits:
Object
  • Object
show all
Defined in:
lib/bubbles/endpoint.rb

Overview

Representation of a single API endpoint within the Bubbles infrastructure.

In order to access an API Endpoint, an RestEnvironment must also be provided. This class is an abstract representation of an Endpoint, without any information provided as part of the Environment. In other words, an Endpoint can be used with any RestEnvironment.

Constant Summary collapse

API_URL =

A template for specifying the complete URL for endpoints.

::Addressable::Template.new("{scheme}://{host}/{endpoint}")
API_URL_WITH_PORT =

A template for specifying the complete URL for endpoints, with a port attached to the host.

::Addressable::Template.new("{scheme}://{host}:{port}/{endpoint}")
METHODS =

The HTTP methods supported by a rest client utilizing Bubbles.

%w[get post patch put delete head].freeze
RETURN_TYPES =

The possible return types for successful REST calls. Defaults to :body_as_string.

%w[full_response body_as_string body_as_object].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method, location, auth_required = false, api_key_required = false, name = nil, return_type = :body_as_string, encode_authorization = {}, headers = {}) ⇒ Endpoint

Construct a new instance of an Endpoint.

Parameters:

  • method (Symbol) —

    The type of the new Endpoint to create. Must be one of the methods in METHODS.

  • location (String) —

    The location, relative to the root of the host, at which the endpoint resides.

  • auth_required (Boolean) (defaults to: false) —

    If true, then authorization/authentication is required to access this endpoint. Defaults to false.

  • api_key_required (Boolean) (defaults to: false) —

    If true, then an API key is required to access this endpoint. Defaults to false.

  • name (String) (defaults to: nil) —

    An optional name which will be given to the method that will execute this Bubbles::Endpoint within the context of a RestClientResources object.

  • encode_authorization (Array<Symbol>) (defaults to: {}) —

    Parameters that should be treated as authorization parameters and encoded using a Base64 encoding.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/bubbles/endpoint.rb', line 77

def initialize(method, location, auth_required = false, api_key_required = false, name = nil, return_type = :body_as_string, encode_authorization = {}, headers = {})
  @method = method
  @location = location
  @auth_required = auth_required
  @api_key_required = api_key_required
  @name = name
  @encode_authorization = encode_authorization
  @additional_headers = headers

  unless Endpoint::RETURN_TYPES.include? return_type.to_s
    return_type = :body_as_string
  end

  @return_type = return_type

  @uri_params = []

  # Strip the leading slash from the endpoint location, if it's there
  if @location.to_s[0] == '/'
    @location = @location.to_s.slice(1, @location.to_s.length)
  end

  # Extract URI parameters and create symbols for them
  # URI parameters are enclosed by curly braces '{' and '}'
  @location.to_s.split('/').each do |uri_segment|

    match_data = /\{(.*)\}/.match(uri_segment)
    unless match_data == nil
      @uri_params.push(match_data[1].to_sym)
    end
  end
end

Instance Attribute Details

#api_key_required ⇒ Boolean

Controls whether an API key is required to access this endpoint. Defaults to false.

Returns:

  • (Boolean) —

    true, if an API key is required to access this endpoint; false, otherwise.



31
32
33
 
# File 'lib/bubbles/endpoint.rb', line 31

def api_key_required
  @api_key_required
end

#authentication_required ⇒ Boolean

Controls whether authentication is required to access this endpoint. Defaults to false.

Returns:

  • (Boolean) —

    true, if authentication is required to access this endpoint; false, otherwise.



26
27
28
 
# File 'lib/bubbles/endpoint.rb', line 26

def authentication_required
  @authentication_required
end

#encode_authorization ⇒ Array

Controls which data values should be encoded as part of an Authorization header. They will be separated with a colon in the order they are received and Base64-encoded.

Returns:

  • (Array) —

    An array of Symbols specifying which of the data attributes should be Base64-encoded as part of an Authorization header. The values will be encoded in the order they are received.



44
45
46
 
# File 'lib/bubbles/endpoint.rb', line 44

def encode_authorization
  @encode_authorization
end

#location ⇒ String

Controls the location, relative to the web root of the host, used to access the endpoint.

Returns:

  • (String) —

    the location relative to the web root of the host used to access the endpoint



21
22
23
 
# File 'lib/bubbles/endpoint.rb', line 21

def location
  @location
end

#method ⇒ Symbol

Controls the method used to access the endpoint. Must be one of Endpoint::Methods.

Returns:

  • (Symbol) —

    the method used to access the endpoint. Will always be one of the symbols defined in METHODS.



16
17
18
 
# File 'lib/bubbles/endpoint.rb', line 16

def method
  @method
end

#return_type ⇒ Object

Retrieve the return type of this REST endpoint.

This will always be one of:

  • full_response : Indicates that the full Response object should be returned so that headers and return code can be used.

  • body_as_object : Indicates that the body of the Response should be parsed as a full OpenStruct object and returned.

  • body_as_string : Indicates that only the body of the Response object should be returned, as a String.

By default, if this is not specified, it will be body_asstring+.



37
38
39
 
# File 'lib/bubbles/endpoint.rb', line 37

def return_type
  @return_type
end

#uri_params ⇒ Object

An array of parameters that are specified on the URI of this endpoint for each call.



48
49
50
 
# File 'lib/bubbles/endpoint.rb', line 48

def uri_params
  @uri_params
end

Instance Method Details

#additional_headers ⇒ Object 



274
275
276
277
278
279
280
 
# File 'lib/bubbles/endpoint.rb', line 274

def additional_headers
  unless @additional_headers
    @additional_headers = {}
  end

  @additional_headers
end

#api_key_required? ⇒ Boolean

Determine if an API key is required

Returns:

  • (Boolean) —

    true, if an API key is required to make the request; false, otherwise.



210
211
212
 
# File 'lib/bubbles/endpoint.rb', line 210

def api_key_required?
  api_key_required
end

#authenticated? ⇒ Boolean

Determine if this Endpoint requires authentication/authorization to utilize

Returns:

  • (Boolean) —

    true, if this Endpoint requires authentication/authorization to use; false, otherwise.



202
203
204
 
# File 'lib/bubbles/endpoint.rb', line 202

def authenticated?
  @auth_required
end

#encode_authorization_header? ⇒ Boolean

Whether or not an Authorization header should be Base64-encoded.

Returns:

  • (Boolean) —

    true, if attributes from the data array have been specified to be Base64-encoded as part of an Authorization header; false, otherwise.



249
250
251
 
# File 'lib/bubbles/endpoint.rb', line 249

def encode_authorization_header?
  !@encode_authorization.nil? and @encode_authorization.length > 0
end

#get_base_url(env) ⇒ Addressable::Template

Retrieve the base URL template for this Endpoint, given a RestEnvironment.

Parameters:

  • env (RestEnvironment) —

    The RestEnvironment to use to access this endpoint.

Returns:

  • (Addressable::Template) —

    A Template containing the URL to use to access this Endpoint.



136
137
138
139
140
141
142
 
# File 'lib/bubbles/endpoint.rb', line 136

def get_base_url(env)
  unless env.port == 80 || env.port == 443
    return API_URL_WITH_PORT
  end

  API_URL
end

#get_expanded_url(env, uri_params = {}) ⇒ Addressable::URI

Retrieve the URL to access this Endpoint, as a String with all parameters expanded.

Parameters:

  • env (RestEnvironment) —

    The RestEnvironment to use to access this Endpoint.

Returns:

  • (Addressable::URI) —

    An Addressable::URI containing the full URL to access this Endpoint on the given RestEnvironment.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/bubbles/endpoint.rb', line 152

def get_expanded_url(env, uri_params = {})
  url = get_base_url env

  if is_complex?
    special_url_string = '{scheme}://{host}/'
    unless @port == 80 || @port == 443
      special_url_string = '{scheme}://{host}:{port}/'
    end

    special_url_string = special_url_string + @location

    uri_params.each do |param, value|
      needle = "{#{param.to_s}}"
      special_url_string = special_url_string.sub(needle, value.to_s)
    end

    url = ::Addressable::Template.new(special_url_string)

    return url.expand(scheme: env.scheme, host: env.host, port: env.port)
  end

  url.expand(scheme: env.scheme, host: env.host, port: env.port, endpoint: @location)
end

#get_key_string ⇒ String

Retrieve a String that will identify this Endpoint uniquely within a hash table.

Returns:

  • (String) —

    A unique identifier for this Endpoint, including its method (get/post/put/etc..), location, whether or not it is authenticated, and whether it needs an API key to successfully execute.



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/bubbles/endpoint.rb', line 115

def get_key_string
  auth_string = '-unauthenticated'
  if @auth_required
    auth_string = '-authenticated'
  end

  api_key_string = ''
  if @api_key_required
    api_key_string = '-with-api-key'
  end

  method.to_s + "-" + @location.to_s + auth_string + api_key_string
end

#get_location_string ⇒ String

Retrieve a String representing the location of this Endpoint.

Complex Endpoints will have instances of ‘/’ replaced with ‘_’.

Returns:

  • (String) —

    The string representation of the location of this endpoint.



190
191
192
193
194
195
196
 
# File 'lib/bubbles/endpoint.rb', line 190

def get_location_string
  unless is_complex?
    return @location
  end

  @location.to_s.gsub('/', '_')
end

#has_additional_headers? ⇒ Boolean

Returns:

  • (Boolean) 


282
283
284
 
# File 'lib/bubbles/endpoint.rb', line 282

def has_additional_headers?
  not additional_headers.empty?
end

#has_uri_params? ⇒ Boolean

Returns:

  • (Boolean) 


270
271
272
 
# File 'lib/bubbles/endpoint.rb', line 270

def has_uri_params?
  !@uri_params.empty?
end

#is_complex? ⇒ Boolean

Determine if the location for this Endpoint is complex.

Returns:

  • (Boolean) —

    true, if the location for this Endpoint is complex (contains a ‘/’); false, otherwise.



180
181
182
 
# File 'lib/bubbles/endpoint.rb', line 180

def is_complex?
  @location.include? '/'
end

#name ⇒ String

Retrieve the name of the method on RestClientResources used to access this Bubbles::Endpoint.

Returns:



229
230
231
 
# File 'lib/bubbles/endpoint.rb', line 229

def name
  @name
end

#name=(name) ⇒ Object

Set the name of the method on RestClientResources used to access this Bubbles::Endpoint.

Parameters:



219
220
221
 
# File 'lib/bubbles/endpoint.rb', line 219

def name=(name)
  @name = name
end

#name? ⇒ Boolean

Determine if this Bubbles::Endpoint has a method name, different from the location name, specified for it.

Returns:

  • (Boolean) —

    true, if this Bubbles::Endpoint has a method name that is different than the location name specified for the Endpoint, to be defined on RestClientResources; false, otherwise.



239
240
241
 
# File 'lib/bubbles/endpoint.rb', line 239

def name?
  @name != nil
end