class Bubbles::Endpoint

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.

Constants

API_URL

A template for specifying the complete URL for endpoints.

API_URL_WITH_PORT

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

METHODS

The HTTP methods supported by a rest client utilizing Bubbles.

RETURN_TYPES

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

Attributes

api_key_required[RW]

Controls whether an API key is required to access this endpoint. Defaults to false. @return [Boolean] true, if an API key is required to access this endpoint; false, otherwise.

authentication_required[RW]

Controls whether authentication is required to access this endpoint. Defaults to false. @return [Boolean] true, if authentication is required to access this endpoint; false, otherwise.

encode_authorization[RW]

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. @return [Array] An array of +Symbol+s 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.
location[RW]

Controls the location, relative to the web root of the host, used to access the endpoint. @return [String] the location relative to the web root of the host used to access the endpoint

method[RW]

Controls the method used to access the endpoint. Must be one of {Endpoint::Methods}. @return [Symbol] the method used to access the endpoint. Will always be one of the symbols defined in

{Endpoint::METHODS}.
return_type[RW]

Controls what type of object will be returned from the REST API call on success. Must be one of the symbols defined in {Endpoint::RETURN_TYPES}.

uri_params[RW]

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

Public Class Methods

new(method, location, auth_required = false, api_key_required = false, name = nil, return_type = :body_as_string, encode_authorization = {}, headers = {}) click to toggle source

Construct a new instance of an Endpoint.

@param [Symbol] method The type of the new Endpoint to create. Must be one of the methods in

{Endpoint::METHODS}.

@param [String] location The location, relative to the root of the host, at which the endpoint resides. @param [Boolean] auth_required If true, then authorization/authentication is required to access this endpoint.

Defaults to +false+.

@param [Boolean] api_key_required If true, then an API key is required to access this endpoint. Defaults to

+false+.

@param [String] name An optional name which will be given to the method that will execute this {Endpoint} within

the context of a {RestClientResources} object.

@param [Array<Symbol>] encode_authorization Parameters that should be treated as authorization parameters and

encoded using a Base64 encoding.
# 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

Public Instance Methods

additional_headers() click to toggle source
# File lib/bubbles/endpoint.rb, line 274
def additional_headers
  unless @additional_headers
    @additional_headers = {}
  end

  @additional_headers
end
api_key_required?() click to toggle source

Determine if an API key is required

@return [Boolean] true, if an API key is required to make the request; false, otherwise.

# File lib/bubbles/endpoint.rb, line 210
def api_key_required?
  api_key_required
end
authenticated?() click to toggle source

Determine if this Endpoint requires authentication/authorization to utilize

@return [Boolean] true, if this Endpoint requires authentication/authorization to use; false, otherwise.

# File lib/bubbles/endpoint.rb, line 202
def authenticated?
  @auth_required
end
encode_authorization_header?() click to toggle source

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

@return [Boolean] true, if attributes from the data array have been specified to be Base64-encoded as part of an

Authorization header; false, otherwise.
# File lib/bubbles/endpoint.rb, line 249
def encode_authorization_header?
  !@encode_authorization.nil? and @encode_authorization.length > 0
end
get_base_url(env) click to toggle source

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

@param [RestEnvironment] env The RestEnvironment to use to access this endpoint.

@return [Addressable::Template] A Template containing the URL to use to access this Endpoint.

# 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 = {}) click to toggle source

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

@param [RestEnvironment] env The RestEnvironment to use to access this Endpoint.

@return [Addressable::URI] An Addressable::URI containing the full URL to access this Endpoint on the given

+RestEnvironment+.
# 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() click to toggle source

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

@return [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.

# 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() click to toggle source

Retrieve a String representing the location of this Endpoint.

Complex Endpoints will have instances of '/' replaced with '_'.

@return [String] The string representation of the location of this endpoint.

# 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?() click to toggle source
# File lib/bubbles/endpoint.rb, line 282
def has_additional_headers?
  not additional_headers.empty?
end
has_uri_params?() click to toggle source
# File lib/bubbles/endpoint.rb, line 270
def has_uri_params?
  !@uri_params.empty?
end
is_complex?() click to toggle source

Determine if the location for this Endpoint is complex.

@return [Boolean] true, if the location for this Endpoint is complex (contains a '/'); false, otherwise.

# File lib/bubbles/endpoint.rb, line 180
def is_complex?
  @location.include? '/'
end
name() click to toggle source

Retrieve the name of the method on {RestClientResources} used to access this {Endpoint}.

@return [String] A String containing the name of the method on {RestClientResources} used to access this

{Endpoint}, or +nil+ if one wasn't provided.
# File lib/bubbles/endpoint.rb, line 229
def name
  @name
end
name=(name) click to toggle source

Set the name of the method on {RestClientResources} used to access this {Endpoint}.

@param [String] name The name of the method used to access this {Endpoint}.

# File lib/bubbles/endpoint.rb, line 219
def name=(name)
  @name = name
end
name?() click to toggle source

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

@return [Boolean] true, if this {Endpoint} has a method name that is different than the location name specified

for the +Endpoint+, to be defined on {RestClientResources}; false, otherwise.
# File lib/bubbles/endpoint.rb, line 239
def name?
  @name != nil
end