bubbles-rest-client 0.0.6

data/lib/bubbles/config.rb

@@ -0,0 +1,201 @@
+require 'bubbles/rest_environment'
+
+module Bubbles
+  class << self
+    attr_writer :configuration
+  end
+
+  ##
+  # Configure the Bubbles instance.
+  #
+  # Use this method if you want to configure the Bubbles instance, typically during intialization of your Gem or
+  # application.
+  #
+  # @example In app/config/initializers/bubbles.rb
+  #    Bubbles.configure do |config|
+  #      config.endpoints = [
+  #        {
+  #          :type => :get,
+  #          :location => :version,
+  #          :authenticated => false,
+  #          :api_key_required => false
+  #        }
+  #      ]
+  #    end
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  ##
+  # The configuration of the Bubbles rest client.
+  #
+  # Use this class if you want to retrieve configuration values set during initialization.
+  #
+  class Configuration
+    def initialize
+      @local_environment_scheme = 'http'
+      @local_environment_host = '127.0.0.1'
+      @local_environment_port = '1234'
+
+      @staging_environment_scheme = 'http'
+      @staging_environment_host = '127.0.0.1'
+      @staging_environment_port = '1234'
+
+      @production_environment_scheme = 'http'
+      @production_environment_host = '127.0.0.1'
+      @production_environment_port = '1234'
+
+      @endpoints = Hash.new
+    end
+
+    ##
+    # Retrieve the local {RestEnvironment} object defined as part of this Configuration.
+    #
+    def local_environment
+      RestEnvironment.new(@local_environment_scheme, @local_environment_host, @local_environment_port)
+    end
+
+    ##
+    # Set the local environment.
+    #
+    # @param [Object] env The environment, as a generic Ruby Object.
+    #
+    # @example In app/config/initializers/bubbles.rb
+    #    Bubbles.configure do |config|
+    #      config.local_environment = {
+    #         :scheme => 'https',
+    #         :host => 'api.somehost.com',
+    #         :port => '443'
+    #      }
+    #    end
+    #
+    def local_environment=(env)
+      @local_environment_scheme = env[:scheme]
+      @local_environment_host = env[:host]
+      @local_environment_port = env[:port]
+    end
+
+    ##
+    # Retrieve the staging {RestEnvironment} object defined as part of this Configuration.
+    #
+    def staging_environment
+      RestEnvironment.new(@staging_environment_scheme, @staging_environment_host, @staging_environment_port)
+    end
+
+    ##
+    # Set the staging environment.
+    #
+    # @param [Object] env The environment, as a generic Ruby Object.
+    #
+    # @example In app/config/initializers/bubbles.rb
+    #    Bubbles.configure do |config|
+    #      config.staging_environment = {
+    #         :scheme => 'https',
+    #         :host => 'api.somehost.com',
+    #         :port => '443'
+    #      }
+    #    end
+    #
+    def staging_environment=(env)
+      @staging_environment_scheme = env[:scheme]
+      @staging_environment_host = env[:host]
+      @staging_environment_port = env[:port]
+    end
+
+    ##
+    # Retrieve the production {RestEnvironment} object defined as part of this Configuration.
+    #
+    def production_environment
+      RestEnvironment.new(@production_environment_scheme, @production_environment_host, @production_environment_port)
+    end
+
+    ##
+    # Set the production environment.
+    #
+    # @param [Object] env The environment, as a generic Ruby Object.
+    #
+    # @example In app/config/initializers/bubbles.rb
+    #    Bubbles.configure do |config|
+    #      config.production_environment = {
+    #         :scheme => 'https',
+    #         :host => 'api.somehost.com',
+    #         :port => '443'
+    #      }
+    #    end
+    #
+    def production_environment=(env)
+      @production_environment_scheme = env[:scheme]
+      @production_environment_host = env[:host]
+      @production_environment_port = env[:port]
+    end
+
+    ##
+    # Retrieve the list of +Endpoint+s configured in this +Configuration+ object.
+    #
+    # @return {Array} An Array of {Endpoint}s.
+    #
+    def endpoints
+      @endpoints
+    end
+
+    ##
+    # Add all {Endpoint} objects within this {Configuration} instance.
+    #
+    # {Endpoint} objects are defined using two required parameters: type and location, and three optional parameters:
+    # authenticated, api_key_required and name.
+    #   - method: Indicates the HTTP method used to access the endpoint. Must be one of {Endpoint::METHODS}.
+    #   - location: Indicates the path at which the {Endpoint} can be accessed on the host environment.
+    #   - authenticated: (Optional) A true or false value indicating whether the {Endpoint} requires an authorization
+    #                    token to access it. Defaults to false.
+    #   - api_key_required: (Optional) A true or false value indicating whether the {Endpoint} requires a API key to
+    #                       access it. Defaults to false.
+    #   - name: (Optional): A +String+ indicating the name of the method to add. If not provided, the method name will
+    #           be the same as the +location+.
+    #
+    def endpoints=(endpoints)
+      new_endpoints = Hash.new
+      endpoints.each do |ep|
+        endpoint_object = Endpoint.new ep[:method], ep[:location].to_s, ep[:authenticated], ep[:api_key_required], ep[:name]
+
+        new_endpoints[endpoint_object.get_key_string] = endpoint_object
+      end
+
+      @endpoints = new_endpoints
+
+      # Define all of the endpoints as methods on RestEnvironment
+      @endpoints.values.each do |endpoint|
+        if endpoint.name != nil
+          endpoint_name_as_sym = endpoint.name.to_sym
+        else
+          endpoint_name_as_sym = endpoint.get_location_string.to_sym
+        end
+
+        if Bubbles::RestEnvironment.instance_methods(false).include? (endpoint_name_as_sym)
+          Bubbles::RestEnvironment.class_exec do
+            remove_method endpoint_name_as_sym
+          end
+        end
+
+        if endpoint.method == :get
+          if endpoint.authenticated?
+            Bubbles::RestEnvironment.class_exec do
+              define_method(endpoint_name_as_sym) do |auth_token|
+                RestClientResources.execute_get_authenticated self, endpoint, auth_token
+              end
+            end
+          else
+            Bubbles::RestEnvironment.class_exec do
+              define_method(endpoint_name_as_sym) do
+                RestClientResources.execute_get_unauthenticated self, endpoint
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bubbles/endpoint.rb

@@ -0,0 +1,181 @@
+require 'addressable/template'
+
+module Bubbles
+  ##
+  # 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+.
+  #
+  class Endpoint
+    ## 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}.
+    attr_accessor :method
+
+    ## 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
+    attr_accessor :location
+
+    ## 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.
+    attr_accessor :authentication_required
+
+    ## 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.
+    attr_accessor :api_key_required
+
+    ## A template for specifying the complete URL for endpoints.
+    API_URL = ::Addressable::Template.new("{scheme}://{host}/{endpoint}")
+
+    ## A template for specifying the complete URL for endpoints, with a port attached to the host.
+    API_URL_WITH_PORT = ::Addressable::Template.new("{scheme}://{host}:{port}/{endpoint}")
+
+
+    ## The HTTP methods supported by a rest client utilizing Bubbles.
+    METHODS = %w[get].freeze
+
+    ##
+    # 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.
+    #
+    def initialize(method, location, auth_required = false, api_key_required = false, name = nil)
+      @method = method
+      @location = location
+      @auth_required = auth_required
+      @api_key_required = api_key_required
+      @name = name
+
+      # 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
+    end
+
+    ##
+    # 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.
+    #
+    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
+
+    ##
+    # 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+.
+    #
+    def get_base_url(env)
+      unless env.port == 80 || env.port == 443
+        return API_URL_WITH_PORT
+      end
+
+      API_URL
+    end
+
+    ##
+    # 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 [String] A +String+ containing the full URL to access this +Endpoint+ on the given {RestEnvironment}.
+    #
+    def get_expanded_url(env)
+      url = get_base_url env
+
+      if is_complex?
+        special_url_string = '{scheme}://{environment_host}/'
+        unless @port == 80 || @port == 443
+          special_url_string = '{scheme}://{environment_host}:{port}/'
+        end
+
+        special_url_string = special_url_string + @location
+        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
+
+    ##
+    # Determine if the location for this Endpoint is complex.
+    #
+    # @return [Boolean] true, if the location for this Endpoint is complex (contains a '/'); false, otherwise.
+    def is_complex?
+      @location.include? '/'
+    end
+
+    ##
+    # 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.
+    def get_location_string
+      unless is_complex?
+        return @location
+      end
+
+      @location.to_s.gsub('/', '_')
+    end
+
+    ##
+    # Determine if this +Endpoint+ requires authentication/authorization to utilize
+    #
+    # @return [Boolean] true, if this +Endpoint+ requires authentication/authorization to use; false, otherwise.
+    def authenticated?
+      @auth_required
+    end
+
+    ##
+    # 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}.
+    #
+    def name=(name)
+      @name = name
+    end
+
+    ##
+    # 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.
+    #
+    def name
+      @name
+    end
+
+    ##
+    # 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.
+    #
+    def name?
+      @name == nil
+    end
+  end
+end

data/lib/bubbles/rest_client_resources.rb

@@ -0,0 +1,124 @@
+require 'bubbles/config'
+require 'bubbles/rest_environment'
+
+module Bubbles
+  class RestClientResources
+    def local_environment
+      Bubbles.configuration.local_environment
+    end
+
+    def staging_environment
+      Bubbles.configuration.staging_environment
+    end
+
+    def production_environment
+      Bubbles.configuration.production_environment
+    end
+
+    ##
+    # Create a new instance of +RestClientResources+.
+    #
+    # @param env The +RestEnvironment+ that should be used for this set of resources.
+    # @param api_key The API key to use to send to the host for unauthenticated requests.
+    #
+    def initialize(env, api_key)
+      unless env
+        env = :local
+      end
+
+      unless api_key
+        api_key = ''
+      end
+
+      @environment = get_environment env
+      @api_key = api_key
+      @auth_token = nil
+    end
+
+    ##
+    # Execute a GET request without authentication.
+    #
+    # @param [RestEnvironment] env The +RestEnvironment+ to use to execute the request
+    # @param [Endpoint] endpoint The +Endpoint+ which should be requested
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the GET call.
+    #
+    def self.execute_get_unauthenticated(env, endpoint)
+      url = endpoint.get_expanded_url env
+
+      begin
+        if env.scheme == 'https'
+          response = RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .get({
+                   :content_type => :json,
+                   :accept => :json
+                 })
+        else
+          response = RestClient.get(url.to_s,
+                                    {
+                                      :content_type => :json
+                                    })
+        end
+      rescue Errno::ECONNREFUSED
+        return {:error => 'Unable to connect to host ' + env.host.to_s + ':' + env.port.to_s}.to_json
+      end
+
+      response
+    end
+
+    ##
+    # Execute a GET request with authentication.
+    #
+    # Currently, only Authorization: Bearer is supported.
+    #
+    # @param [RestEnvironment] env The +RestEnvironment+ to use to execute the request
+    # @param [Endpoint] endpoint The +Endpoint+ which should be requested
+    # @param [String] auth_token The authorization token to use for authentication.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the GET call.
+    #
+    def self.execute_get_authenticated(env, endpoint, auth_token)
+      url = endpoint.get_expanded_url env
+
+      begin
+        if env.scheme == 'https'
+          response = RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .get({
+                   :authorization => 'Bearer ' + auth_token,
+                   :content_type => :json,
+                   :accept => :json
+                 })
+        else
+          response = RestClient.get(url.to_s,
+                                    {
+                                      :authorization => 'Bearer ' + auth_token,
+                                      :content_type => :json
+                                    })
+        end
+      rescue Errno::ECONNREFUSED
+        return {:error => 'Unable to connect to host ' + env.host.to_s + ':' + env.port.to_s}.to_json
+      end
+
+      response
+    end
+
+    ##
+    # Retrieve the {RestEnvironment} to utilize from a {Symbol} describing it.
+    #
+    # @param [Symbol] environment A {Symbol} describing the environment to use. Must be one of:
+    #        [:production, :staging, :local, nil]. If +nil+, note that +:production+ will be used.
+    #
+    # @return [RestEnvironment] The {RestEnvironment} corresponding to the given {Symbol}.
+    #
+    def get_environment(environment)
+      if !environment || environment == :production
+        return self.production_environment
+      elsif environment == :staging
+        return self.staging_environment
+      end
+
+
+      self.local_environment
+    end
+  end
+end