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 = {}) ⇒ Endpoint

Construct a new instance of an Endpoint.

Parameters:

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

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

  • (defaults to: false)

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

  • (defaults to: false)

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

  • (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.

  • (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
 
# 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 = {})
  @method = method
  @location = location
  @auth_required = auth_required
  @api_key_required = api_key_required
  @name = name
  @encode_authorization = encode_authorization

  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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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

#api_key_required? ⇒ Boolean

Determine if an API key is required

Returns:

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



208
209
210
 
# File 'lib/bubbles/endpoint.rb', line 208

def api_key_required?
  api_key_required
end

#authenticated? ⇒ Boolean

Determine if this Endpoint requires authentication/authorization to utilize

Returns:

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



200
201
202
 
# File 'lib/bubbles/endpoint.rb', line 200

def authenticated?
  @auth_required
end

#encode_authorization_header? ⇒ Boolean

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

Returns:

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



247
248
249
 
# File 'lib/bubbles/endpoint.rb', line 247

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:

  • The RestEnvironment to use to access this endpoint.

Returns:

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



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

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 = {}) ⇒ String

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

Parameters:

  • The RestEnvironment to use to access this Endpoint.

Returns:

  • A String containing the full URL to access this Endpoint on the given RestEnvironment.



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

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:

  • 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.



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

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:

  • The string representation of the location of this endpoint.



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

def get_location_string
  unless is_complex?
    return @location
  end

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

#has_uri_params? ⇒ Boolean

Returns:



268
269
270
 
# File 'lib/bubbles/endpoint.rb', line 268

def has_uri_params?
  !@uri_params.empty?
end

#is_complex? ⇒ Boolean

Determine if the location for this Endpoint is complex.

Returns:

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



178
179
180
 
# File 'lib/bubbles/endpoint.rb', line 178

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

#name ⇒ String

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

Returns:



227
228
229
 
# File 'lib/bubbles/endpoint.rb', line 227

def name
  @name
end

#name=(name) ⇒ Object

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

Parameters:



217
218
219
 
# File 'lib/bubbles/endpoint.rb', line 217

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:



237
238
239
 
# File 'lib/bubbles/endpoint.rb', line 237

def name?
  @name == nil
end