bubbles-rest-client 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f8bdd1fabbb4307f261d1d1a0964d3e6e1cd0ab
-  data.tar.gz: 91aafd3870051c1960a1a3038a0625b2383f48ca
+  metadata.gz: 3db39174193ea887659c8e1d859048526b0c5335
+  data.tar.gz: 8254a56110041009e0e03c32aae4b1a1de08b914
 SHA512:
-  metadata.gz: c47bd2636eb96aff3ffd058ea682e22547099f96c8f2f683d8b2b8b2a371cd5be29ed63d39651723eef283ef4f4620d638cc99d8e9f2b87c85ea6e93e176d7c6
-  data.tar.gz: 90572682aa9b7f686b21e96758f0ee50af6adc20d902f5894996e42457fb3ed496305bb18c8f52cd1f1e0a07cfdca5d04eb22ad18d4a4dbaa8be8dd9f9349c41
+  metadata.gz: 8c0f6e722b868cf82d60f0a12e17b3ea24cc59f65ea756e93bf07d906670b49dd700a44f2f2631b0d1ef6ff264bfa0c13d1c74dfaf2e26e7944f1d3ae175924e
+  data.tar.gz: 3211a7eda8805bdba2678c551f73dd8212d188ce371a4a3a526010b8a6507071f5ba41d41ef93a253afa37bf99b5a3f955f9098f963d0b3f83dfbc79078744a7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bubbles-rest-client (0.0.7)
+    bubbles-rest-client (0.1.0)
       addressable (~> 2.5)
       rest-client (~> 2.0)
 

data/README.md

@@ -22,3 +22,158 @@ GitHubService service = retrofit.create(GitHubService.class);
 What this does is allow you to focus on your _handling_ of the REST responses, rather than worrying about the boilerplate code required to set up the client side of the REST API.
 
 _bubbles_ is a Gem that seeks to provide this same behavior.
+
+## :warning: Limitations
+**Please read this section before using!**
+
+Currently, bubbles has a number of limitations that make it likely not suitable for use in a production environment. Each of these is tracked by an issue on our [issues page](https://github.com/FoamFactory/bubbles/issues).
+
+  - Passing an API key with a request is restricted to using `X-Api-Key` as a header key (#10).
+  - Some request methods (`PATCH`, `PUT`, `DELETE`) do not currently allow unauthenticated access. In other words, it is not possible to perform a `DELETE` request on your API without passing an authorization token. (#9)
+  - Only three types of environment are currently allowed. Only `local`, `staging` and `production` are recognized as possible environments to connect to for the purposes of using bubbles. You can add any scheme, host, and port to any of these, but the names are currently hardcoded, as is the number of possible hosts. (#4)
+  - Not all possible combinations of `has_uri_params`, `authenticated`, and `api_key_required` are tested. In some cases, such as with `GET` requests, there aren't any tests for possible configuration cases that might cause issues when combined. (#12)
+  - Usage of the `expect_json` configuration parameter is not intuitive. You should think of this as more of a "I want an object back from the API", rather than how it's worded. (#11)
+
+If you're interested in working on any of the issues above, please feel free to submit a pull request and a member of our team will review that pull request within a couple of days.
+
+## Usage
+If you're using Rails, it's suggested to have a `config/initializers/bubbles.rb` configuration file where you can easily configure your endpoints and environments. If you're not using Rails, then you can put this configuration just about anywhere, provided it's executed before where you want to use it.
+
+## Quickstart
+In `config/initializers/bubbles.rb`, add the following:
+```ruby
+require 'bubbles'
+
+Bubbles.configure do |config|
+  config.endpoints = [
+    {
+      :method => :get,
+      :location => :version,
+      :authenticated => false,
+      :api_key_required => false
+    }
+  ]
+
+  config.local_environment = {
+    :scheme => 'http',
+    :host => '0.0.0.0',
+    :port => '1234'
+  }
+end
+```
+
+The `config.endpoints` section is where you configure which endpoints you want to support. The `config.local_environment` defines an environment, or remote configuration, for accessing the endpoint on a specific remote destination.
+
+Now, you can use this endpoint with:
+```ruby
+require 'bubbles'
+
+...
+
+def version
+  resources = Bubbles::Resources.new
+
+  # The following will make a GET request to
+  # http://0.0.0.0:1234/version and return the result.
+  result = resources.local_environment.version
+
+  puts(result)
+end
+```
+
+## Detailed Documentation
+There are currently two parts to a bubbles configuration: the _environments_ and the _endpoints_. Bubbles is configured in a _bubbles configuration block_:
+```ruby
+Bubbles.configure do |config|
+...
+end
+```
+
+This configuration block can be run at any time, but is typically set up in the initializer section of an app's startup. If desired, configuration can happen separately. That is, you can initialize environments within your initializer file and then initialize endpoints within another section of the application. Just note that when endpoints are defined, it overwrites _all_ endpoints of a configuration, not just the ones you choose to change.
+
+### Environments
+Three environments are currently available to be set up within bubbles. These are:
+  - `local_environment` : Designed to be used for a local API for development testing.
+  - `staging_environment` : Designed to be used for a remote API for second-stage testing or production-like deployment.
+  - `production_environment` : Designed to be used for a production environment.
+
+While the names are hardcoded, the environments can be used for anything - you could easily use a `local_environment` to store the information for one of your production servers.
+
+#### Configuration of Environments
+Environments are configured as part of the _bubbles configuration block_ and can have the following parameters:
+
+  - `scheme`: The scheme for accessing endpoints on this host. Should be one of `http` or `https`. Defaults to `http`.
+  - `host`: A domain name or IP address for the remote host to access for the environment.  Defaults to `127.0.0.1`.
+  - `port`: The port to use to access the remote host. Defaults to `1234`.
+  - `api_key`: The API key to send along with requests for a given environment, if an API key is required. This is optional, and defaults to `nil`.
+
+You can configure all three environments at once in the _bubbles configuration block_:
+```ruby
+Bubbles.configure do |config|
+  config.local_environment = {
+    :scheme => 'http',
+    :host => '0.0.0.0',
+    :port => '1234'
+  }
+
+  config.staging_environment = {
+    :scheme => 'http',
+    :host => 'stage.api.foamfactory.com',
+    :port => '80'
+  }
+
+  config.production_environment = {
+    :scheme => 'https',
+    :host => 'api.foamfactory.com',
+    :port => '443'
+  }
+end
+```
+
+If you choose a scheme of `http` and leave off the `port` configuration variable, it will default to `80`. Similarly, `https` will default to a port of `443`.
+
+#### Configuration of Endpoints
+Endpoints are the meat and potatoes of REST interaction. By indicating a _method_, _uri_, _body_, and _headers_, you are effectively making a function call on a remote server.
+
+_Endpoints_ are specified as an array of objects within the _bubbles configuration block_:
+
+```ruby
+config.endpoints = [
+  # Individual endpoint definitions go here
+]
+```
+
+When processing each of these endpoint definitions, a method is created on instances of `RestEnvironment` that allows you to call the method in question. For example, an endpoint defined as:
+```ruby
+{
+  :method => :get,
+  :location => :version,
+  :authenticated => false,
+  :api_key_required => false
+}
+```
+
+will create a method on instances of `RestEnvironment` called `version`, which will execute the appropriate REST call (via `RestClient`) and return a `RestClient::Response` object.
+
+Each _endpoint_ object can have the following attributes:
+
+| Name    | Description         | Required? | Default |
+| :---    | :------------------ | :-------: | :-----: |
+| `method`| The HTTP method to use to access the API for this endpoint. Must be one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, or `HEAD`. | Yes | N/A |
+| `location`| The path to access the endpoint. This is placed after the `host:port` section to build the URI. It may have URI parameters in the form of `{paramName}`. If a URI parameter is specified within the `location`, a `uri_params` hash will be expected to be passed to the calling method to replace the placeholder values. | Yes | N/A |
+| `name` | The name to give the method created to make this REST call. | No | The value of the `location` parameter, with slashes (`/`) replaced with underscores (`_`). |
+| `authorization` | Whether or not this endpoint requires authentication prior to executing the call. If true, then an `authorization_token` will be added to the method as a parameter to be passed when the method is called. This parameter will be placed in an `Authorization` header when the REST call is executed. | No | `false` |
+| `api_key_required` | Whether or not an API key is required. If `true`, a parameter will be added to the method created to execute the REST API call named `api_key`. The value of this parameter will be set as the value of the `X-Api-Key` header when making the REST API call. | No | `false` |
+| `expect_json` | Whether or not JSON is expected as the format of the `body` of both the Request and Response. Additionally, specifying `true` for this option will cause methods executing REST requests to return `OpenStruct` objects representing the fully-parsed JSON response (on success). See note under "Limitations", above, on using this parameter. | No | `false` |
+| `encode_authorization` | Whether the `data` passed as part of the request should be re-encoded as an `Authorization: Basic` header (and Base64 encoded). Typically, this is only used for initial username/password authentication. | No | `false` |
+
+### Examples
+#### GET the version of the software (unauthenticated, no API key required)
+
+#### GET a specific user by id (authentication required)
+
+#### POST a login (i.e. retrieve an authorization token)
+
+#### DELETE a user by id
+
+#### PATCH a user's information by providing a body containing information to update

data/bubbles.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = Bubbles::VersionInformation.version_name
   spec.date        = Date.today.strftime("%Y-%m-%d")
   spec.summary     = 'FoamFactory REST Client'
-  spec.homepage    = 'http://www.foamfactorybrewing.com'
+  spec.homepage    = 'https://github.com/FoamFactory/bubbles'
   spec.authors     = ['Scott Johnson']
   spec.email       = 'jaywir3@gmail.com'
   spec.files       = %w(lib/bubbles.rb lib/bubbles/rest_environment.rb lib/bubbles/version.rb)

data/lib/bubbles/config.rb

@@ -1,5 +1,6 @@
 require 'bubbles/rest_environment'
 require 'bubbles/endpoint'
+require 'base64'
 
 module Bubbles
   class << self
@@ -41,14 +42,17 @@ module Bubbles
       @local_environment_scheme = 'http'
       @local_environment_host = '127.0.0.1'
       @local_environment_port = '1234'
+      @local_environment_api_key = nil
 
       @staging_environment_scheme = 'http'
       @staging_environment_host = '127.0.0.1'
       @staging_environment_port = '1234'
+      @staging_environment_api_key = nil
 
       @production_environment_scheme = 'http'
       @production_environment_host = '127.0.0.1'
       @production_environment_port = '1234'
+      @production_environment_api_key = nil
 
       @endpoints = Hash.new
     end
@@ -57,7 +61,7 @@ module Bubbles
     # 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)
+      RestEnvironment.new(@local_environment_scheme, @local_environment_host, @local_environment_port, @local_environment_api_key)
     end
 
     ##
@@ -78,13 +82,14 @@ module Bubbles
       @local_environment_scheme = env[:scheme]
       @local_environment_host = env[:host]
       @local_environment_port = env[:port]
+      @local_environment_api_key = env[:api_key]
     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)
+      RestEnvironment.new(@staging_environment_scheme, @staging_environment_host, @staging_environment_port, @staging_environment_api_key)
     end
 
     ##
@@ -105,13 +110,14 @@ module Bubbles
       @staging_environment_scheme = env[:scheme]
       @staging_environment_host = env[:host]
       @staging_environment_port = env[:port]
+      @staging_environment_api_key = env[:api_key]
     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)
+      RestEnvironment.new(@production_environment_scheme, @production_environment_host, @production_environment_port, @production_environment_api_key)
     end
 
     ##
@@ -124,7 +130,7 @@ module Bubbles
     #      config.production_environment = {
     #         :scheme => 'https',
     #         :host => 'api.somehost.com',
-    #         :port => '443'
+    #         :port => '443',
     #      }
     #    end
     #
@@ -132,6 +138,7 @@ module Bubbles
       @production_environment_scheme = env[:scheme]
       @production_environment_host = env[:host]
       @production_environment_port = env[:port]
+      @production_environment_api_key = env[:api_key]
     end
 
     ##
@@ -160,7 +167,7 @@ module Bubbles
     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]
+        endpoint_object = Endpoint.new ep[:method], ep[:location].to_s, ep[:authenticated], ep[:api_key_required], ep[:name], ep[:expect_json], ep[:encode_authorization]
 
         new_endpoints[endpoint_object.get_key_string] = endpoint_object
       end
@@ -184,8 +191,14 @@ module Bubbles
         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
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |auth_token, uri_params|
+                  RestClientResources.execute_get_authenticated self, endpoint, auth_token, uri_params
+                end
+              else
+                define_method(endpoint_name_as_sym) do |auth_token|
+                  RestClientResources.execute_get_authenticated self, endpoint, auth_token, {}
+                end
               end
             end
           else
@@ -195,6 +208,155 @@ module Bubbles
               end
             end
           end
+        elsif endpoint.method == :post
+          if endpoint.authenticated?
+            Bubbles::RestEnvironment.class_exec do
+              define_method(endpoint_name_as_sym) do |auth_token, data|
+                RestClientResources.execute_post_authenticated self, endpoint, auth_token, data
+              end
+            end
+          else
+            if endpoint.api_key_required?
+              Bubbles::RestEnvironment.class_exec do
+                define_method(endpoint_name_as_sym) do |data|
+                  additional_headers = {}
+                  if endpoint.encode_authorization_header?
+                    count = 0
+                    auth_value = ''
+                    endpoint.encode_authorization.each { |auth_key|
+                      if data[auth_key]
+                        if count > 0
+                          auth_value = auth_value + ':' + data[auth_key]
+                        else
+                          auth_value = data[auth_key]
+                        end
+
+                        count = count + 1
+
+                        data.delete(auth_key)
+                      end
+                    }
+
+                    additional_headers[:Authorization] = 'Basic ' + Base64.strict_encode64(auth_value)
+                  end
+
+                  RestClientResources.execute_post_with_api_key self, endpoint, self.api_key, data, additional_headers
+                end
+              end
+            else
+              raise 'Unauthenticated POST requests without an API key are not allowed'
+            end
+          end
+        elsif endpoint.method == :delete
+          if endpoint.authenticated?
+            Bubbles::RestEnvironment.class_exec do
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |auth_token, uri_params|
+                  RestClientResources.execute_delete_authenticated self, endpoint, auth_token, uri_params
+                end
+              else
+                # NOTE: While MDN states that DELETE requests with a body are allowed, it seems that a number of
+                # documentation sites discourage its use. Thus, it's possible that, depending on the server API
+                # framework, the DELETE request could be rejected. As such, we're disallowing it here, BUT if we
+                # get feedback from users that it should be supported, we can add support for it.
+                raise 'DELETE requests without URI parameters are not allowed'
+              #   define_method(endpoint_name_as_sym) do |auth_token|
+              #     RestClientResources.execute_delete_authenticated self, endpoint, auth_token, {}
+              #   end
+              end
+            end
+          else
+            raise 'Unauthenticated DELETE requests are not allowed'
+            # Bubbles::RestEnvironment.class_exec do
+              # define_method(endpoint_name_as_sym) do
+              #   RestClientResources.execute_delete_unauthenticated self, endpoint
+              # end
+            # end
+          end
+        elsif endpoint.method == :patch
+          if endpoint.authenticated?
+            Bubbles::RestEnvironment.class_exec do
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |auth_token, uri_params, data|
+                  RestClientResources.execute_patch_authenticated self, endpoint, auth_token, uri_params, data
+                end
+              else
+                define_method(endpoint_name_as_sym) do |auth_token, data|
+                  RestClientResources.execute_patch_authenticated self, endpoint, auth_token, nil, data
+                end
+              end
+            end
+          else
+            raise 'Unauthenticated PATCH requests are not implemented'
+            # Bubbles::RestEnvironment.class_exec do
+            # define_method(endpoint_name_as_sym) do
+            #   RestClientResources.execute_delete_unauthenticated self, endpoint
+            # end
+            # end
+          end
+        elsif endpoint.method == :put
+          if endpoint.authenticated?
+            Bubbles::RestEnvironment.class_exec do
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |auth_token, uri_params, data|
+                  RestClientResources.execute_put_authenticated self, endpoint, auth_token, uri_params, data
+                end
+              else
+                define_method(endpoint_name_as_sym) do |auth_token, data|
+                  RestClientResources.execute_put_authenticated self, endpoint, auth_token, nil, data
+                end
+              end
+            end
+          else
+            raise 'Unauthenticated PUT requests are not implemented'
+            # Bubbles::RestEnvironment.class_exec do
+            # define_method(endpoint_name_as_sym) do
+            #   RestClientResources.execute_delete_unauthenticated self, endpoint
+            # end
+            # end
+          end
+        elsif endpoint.method == :head
+          if endpoint.authenticated?
+            Bubbles::RestEnvironment.class_exec do
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |auth_token, uri_params|
+                  RestClientResources.execute_head_authenticated self, endpoint, auth_token, uri_params
+                end
+              else
+                define_method(endpoint_name_as_sym) do |auth_token|
+                  RestClientResources.execute_head_authenticated self, endpoint, auth_token, {}
+                end
+              end
+            end
+          elsif endpoint.api_key_required?
+            Bubbles::RestEnvironment.class_exec do
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |api_key, uri_params|
+                  additional_headers = {}
+                  additional_headers['X-Api-Key'] = api_key
+                  RestClientResources.execute_head_unauthenticated self, endpoint, uri_params, additional_headers
+                end
+              else
+                define_method(endpoint_name_as_sym) do |api_key|
+                  additional_headers = {}
+                  additional_headers['X-Api-Key'] = api_key
+                  RestClientResources.execute_head_unauthenticated self, endpoint, {}, additional_headers
+                end
+              end
+            end
+          else
+            Bubbles::RestEnvironment.class_exec do
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |uri_params|
+                  RestClientResources.execute_head_unauthenticated self, endpoint, uri_params, {}
+                end
+              else
+                define_method(endpoint_name_as_sym) do
+                  RestClientResources.execute_head_unauthenticated self, endpoint, {}, {}
+                end
+              end
+            end
+          end
         end
       end
     end

data/lib/bubbles/endpoint.rb

@@ -9,22 +9,42 @@ module Bubbles
   # Endpoint can be used with any +RestEnvironment+.
   #
   class Endpoint
-    ## Controls the method used to access the endpoint. Must be one of {Endpoint::Methods}.
+    ##
+    # 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.
+    ##
+    # 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.
+    ##
+    # 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.
+    ##
+    # 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
 
+    ##
+    # Controls whether JSON is the expected form of output from this +Endpoint+.
+    # @return [Boolean] true, if JSON is the expected form of output from this +Endpoint+; false, otherwise.
+    attr_accessor :expect_json
+
+    ##
+    # 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.
+    attr_accessor :encode_authorization
+
+    ##
+    # An array of parameters that are specified on the URI of this endpoint for each call.
+    attr_accessor :uri_params
+
     ## A template for specifying the complete URL for endpoints.
     API_URL = ::Addressable::Template.new("{scheme}://{host}/{endpoint}")
 
@@ -33,7 +53,7 @@ module Bubbles
 
 
     ## The HTTP methods supported by a rest client utilizing Bubbles.
-    METHODS = %w[get].freeze
+    METHODS = %w[get post patch put delete head].freeze
 
     ##
     # Construct a new instance of an Endpoint.
@@ -46,18 +66,32 @@ module Bubbles
     #        +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 [Boolean] expect_json Whether or not to expect a JSON response from this +Endpoint+. Defaults to +false+.
     #
-    def initialize(method, location, auth_required = false, api_key_required = false, name = nil)
+    def initialize(method, location, auth_required = false, api_key_required = false, name = nil, expect_json = false, encode_authorization = {})
       @method = method
       @location = location
       @auth_required = auth_required
       @api_key_required = api_key_required
       @name = name
+      @expect_json = expect_json
+      @encode_authorization = encode_authorization
+      @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
 
     ##
@@ -101,16 +135,22 @@ module Bubbles
     #
     # @return [String] A +String+ containing the full URL to access this +Endpoint+ on the given {RestEnvironment}.
     #
-    def get_expanded_url(env)
+    def get_expanded_url(env, uri_params = {})
       url = get_base_url env
 
       if is_complex?
-        special_url_string = '{scheme}://{environment_host}/'
+        special_url_string = '{scheme}://{host}/'
         unless @port == 80 || @port == 443
-          special_url_string = '{scheme}://{environment_host}:{port}/'
+          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)
@@ -149,6 +189,14 @@ module Bubbles
       @auth_required
     end
 
+    ##
+    # Determine if an API key is required
+    #
+    # @return [Boolean] true, if an API key is required to make the request; false, otherwise.
+    def api_key_required?
+      api_key_required
+    end
+
     ##
     # Set the name of the method on {RestClientResources} used to access this {Endpoint}.
     #
@@ -177,5 +225,19 @@ module Bubbles
     def name?
       @name == nil
     end
+
+    ##
+    # 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.
+    #
+    def encode_authorization_header?
+      @encode_authorization.length > 0
+    end
+
+    def has_uri_params?
+      !@uri_params.empty?
+    end
   end
 end

data/lib/bubbles/rest_client_resources.rb

@@ -44,26 +44,14 @@ module Bubbles
     # @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
+      execute_rest_call(env, endpoint, nil, nil, nil) do |env, url, data, headers|
         if env.scheme == 'https'
-          response = RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
-            .get({
-                   :content_type => :json,
-                   :accept => :json
-                 })
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .get(headers)
         else
-          response = RestClient.get(url.to_s,
-                                    {
-                                      :content_type => :json
-                                    })
+          next RestClient.get(url.to_s, headers)
         end
-      rescue Errno::ECONNREFUSED
-        return {:error => 'Unable to connect to host ' + env.host.to_s + ':' + env.port.to_s}.to_json
       end
-
-      response
     end
 
     ##
@@ -74,32 +62,190 @@ module Bubbles
     # @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.
+    # @param [Hash] uri_params A +Hash+ of identifiers to values to replace in the URI string.
     #
     # @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
+    def self.execute_get_authenticated(env, endpoint, auth_token, uri_params)
+      execute_rest_call(env, endpoint, nil, auth_token, nil, uri_params) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .get(headers)
+        else
+          next RestClient.get(url.to_s, headers)
+        end
+      end
+    end
 
-      begin
+    ##
+    # Execute a HEAD request without authentication.
+    #
+    # This is the same as a GET request, but will only return headers and not the response body.
+    #
+    # @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_head_unauthenticated(env, endpoint, uri_params, additional_headers)
+      execute_rest_call(env, endpoint, nil, nil, additional_headers, uri_params) do |env, url, data, headers|
         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
-                 })
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .head(headers)
         else
-          response = RestClient.get(url.to_s,
-                                    {
-                                      :authorization => 'Bearer ' + auth_token,
-                                      :content_type => :json
-                                    })
+          next RestClient.head(url.to_s, headers)
         end
-      rescue Errno::ECONNREFUSED
-        return {:error => 'Unable to connect to host ' + env.host.to_s + ':' + env.port.to_s}.to_json
       end
+    end
 
-      response
+    ##
+    # Execute a HEAD request with authentication.
+    #
+    # Currently, only Authorization: Bearer is supported. This is the same as a GET request, but will only return
+    # headers and not the response body.
+    #
+    # @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.
+    # @param [Hash] uri_params A +Hash+ of identifiers to values to replace in the URI string.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the GET call.
+    #
+    def self.execute_head_authenticated(env, endpoint, auth_token, uri_params)
+      execute_rest_call(env, endpoint, nil, auth_token, nil, uri_params) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .head(headers)
+        else
+          next RestClient.head(url.to_s, headers)
+        end
+      end
+    end
+
+    ##
+    # Execute a POST request without authentication, but requiring an API key.
+    #
+    # @param [RestEnvironment] env The +RestEnvironment+ to use to execute the request
+    # @param [Endpoint] endpoint The +Endpoint+ which should be requested
+    # @param [String] api_key The API key to use to process the request. Will be placed in an 'X-API-KEY' header.
+    # @param [Hash] data A +Hash+ of key-value pairs that will be sent in the body of the http request.
+    # @param [Hash] headers (Optional) A +Hash+ of key-value pairs that will be sent as HTTP headers as part of the
+    #        request. Defaults to +nil+.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the POST call.
+    #
+    def self.execute_post_with_api_key(env, endpoint, api_key, data, headers=nil)
+      additional_headers = {
+        'X-Api-Key' => api_key
+      }
+
+      unless headers.nil?
+        headers.each { |nextHeader|
+          additional_headers[nextHeader[0]] = nextHeader[1]
+        }
+      end
+
+      execute_rest_call(env, endpoint, data, nil, additional_headers) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .post(data.to_json, additional_headers)
+        else
+          next RestClient.post url.to_s, data.to_json, additional_headers
+        end
+      end
+    end
+
+    ##
+    # Execute a POST request with authentication in the form of an authorization token.
+    #
+    # @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 retrieved during some former authentication call. Will be
+    #        placed into a Authorization header.
+    # @param [Hash] data A +Hash+ of key-value pairs that will be sent in the body of the http request.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the POST call.
+    #
+    def self.execute_post_authenticated(env, endpoint, auth_token, data)
+      return execute_rest_call(env, endpoint, data, auth_token, nil) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .post(data.to_json, headers)
+
+        else
+          next RestClient.post(url.to_s, data.to_json, headers)
+        end
+      end
+    end
+
+    ##
+    # Execute a PATCH request with authentication in the form of an authorization token.
+    #
+    # @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 retrieved during some former authentication call. Will be
+    #        placed into a Authorization header.
+    # @param [Hash] uri_params A +Hash+ of identifiers to values to replace in the URI string.
+    # @param [Hash] data A +Hash+ of key-value pairs that will be sent in the body of the http request.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the PATCH call.
+    #
+    def self.execute_patch_authenticated(env, endpoint, auth_token, uri_params, data)
+      return execute_rest_call(env, endpoint, data, auth_token, nil, uri_params) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .patch(data.to_json, headers)
+
+        else
+          next RestClient.patch(url.to_s, data.to_json, headers)
+        end
+      end
+    end
+
+    ##
+    # Execute a PUT request with authentication in the form of an authorization token.
+    #
+    # @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 retrieved during some former authentication call. Will be
+    #        placed into a Authorization header.
+    # @param [Hash] uri_params A +Hash+ of identifiers to values to replace in the URI string.
+    # @param [Hash] data A +Hash+ of key-value pairs that will be sent in the body of the http request.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the PUT call.
+    #
+    def self.execute_put_authenticated(env, endpoint, auth_token, uri_params, data)
+      return execute_rest_call(env, endpoint, data, auth_token, nil, uri_params) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .put(data.to_json, headers)
+
+        else
+          next RestClient.put(url.to_s, data.to_json, headers)
+        end
+      end
+    end
+
+    ##
+    # Execute a DELETE request with authentication in the form of an authorization token.
+    #
+    # @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 retrieved during some former authentication call. Will be
+    #        placed into a Authorization header.
+    # @param [Hash] uri_params A +Hash+ of identifiers to values to replace in the URI string.
+    #
+    # @return [RestClient::Response] The +Response+ resulting from the execution of the DELETE call.
+    #
+    def self.execute_delete_authenticated(env, endpoint, auth_token, uri_params)
+      execute_rest_call(env, endpoint, nil, auth_token, nil, uri_params) do |env, url, data, headers|
+        if env.scheme == 'https'
+          next RestClient::Resource.new(url.to_s, :verify_ssl => OpenSSL::SSL::VERIFY_NONE)
+            .delete(headers)
+        else
+          next RestClient.delete(url.to_s, headers)
+        end
+      end
     end
 
     ##
@@ -120,5 +266,65 @@ module Bubbles
 
       self.local_environment
     end
+
+    private
+
+    ##
+    # Execute a REST call to the API.
+    #
+    # This is the workhorse of the +RestClientResources+ class. It performs the necessary setup of headers and the HTTP
+    # request, and then executes the remote API call.
+    #
+    # @param [RestEnvironment] env The +RestEnvironment+ to use to make this API call. Must not be +nil+.
+    # @param [Endpoint] The +Endpoint+ to call. Must not be +nil+.
+    # @param [Hash] The body of the request. May be +nil+ or empty for requests not requiring a body.
+    # @param [String] auth_token The authorization token used to authenticate to the API. May be +nil+ for requests that
+    #        don't require authentication.
+    # @param [Hash] headers A +Hash+ of key-value pairs to add to the HTTP request as headers. May be +nil+ if none are
+    #        required.
+    # @param [Block] block The block to execute that actually performs the HTTP request.
+    #
+    # @return [RestClient::Response|OpenStruct] If "expect_json" is enabled for the +Endpoint+ being executed, then this
+    #         will return an +OpenStruct+; otherwise, the +Response+ will be returned.
+    #
+    def self.execute_rest_call(env, endpoint, data, auth_token, headers, uri_params = {}, &block)
+      unless block
+        raise ArgumentError('This method requires that a block is given.')
+      end
+
+      url = endpoint.get_expanded_url env, uri_params
+
+      begin
+        if data == nil
+          data = {}
+        end
+
+        if headers == nil
+          headers = {
+            :content_type => :json
+          }
+        else
+          headers[:content_type] = :json
+        end
+
+        unless auth_token == nil
+          headers[:authorization] = 'Bearer ' + auth_token
+        end
+
+        if endpoint.expect_json
+          headers[:accept] = :json
+        end
+
+        response = block.call(env, url, data, headers)
+      rescue Errno::ECONNREFUSED
+        response = { :error => 'Unable to connect to host ' + env.host.to_s + ':' + env.port.to_s }.to_json
+      end
+
+      unless endpoint.expect_json or endpoint.method != :head
+        return response
+      end
+
+      JSON.parse(response, object_class: OpenStruct)
+    end
   end
 end

data/lib/bubbles/rest_environment.rb

@@ -2,16 +2,17 @@ require 'addressable/template'
 
 module Bubbles
   class RestEnvironment
-    attr_accessor :scheme, :host, :port
+    attr_accessor :scheme, :host, :port, :api_key
 
     ##
     # Construct a new instance of +RestEnvironment+.
     #
-    # @param scheme The scheme to use for communicating with the host. Currently, http and https are supported.
-    # @param host The host to communicate with.
-    # @param port The port on which the communication channel should operate.
+    # @param [String] scheme The scheme to use for communicating with the host. Currently, http and https are supported.
+    # @param [String] host The host to communicate with.
+    # @param [Integer] port The port on which the communication channel should operate.
+    # @param [String] api_key (Optional) The API key to use to identify your client with the API. Defaults to +nil+.
     #
-    def initialize(scheme='https', host='api.foamfactory.com', port=443)
+    def initialize(scheme='https', host='api.foamfactory.com', port=443, api_key=nil)
       @scheme = scheme
       @port = port
 
@@ -20,49 +21,7 @@ module Bubbles
       end
 
       @host = host
+      @api_key = api_key
     end
-
-    ##
-    # Add an unauthenticated endpoint to this +RestEnvironment+.
-    #
-    # @param type The type of the endpoint. Must be one of [:get].
-    # @param endpoint The path to the endpoint, without the leading slash.
-    #
-    # def add_unauthenticated_endpoint(type, endpoint)
-    #   if type == :get
-    #     unless endpoint.include? "/"
-    #       @endpoints[endpoint] = get_url.expand(scheme: @scheme, environment_host: @host, port: @port, endpoint: endpoint).to_s
-    #       return
-    #     end
-    #
-    #     @endpoints[endpoint] = get_url_with_special_endpoint.expand(scheme: @scheme, environment_host: @host, port: @port, endpoint: endpoint).to_s
-    #   end
-    # end
-
-    # def get_endpoint_string(endpoint)
-    #   @endpoints[endpoint]
-    # end
-
-    def get_base_url
-
-    end
-
-    private
-      ##
-      # Get an addressable template for a 'special' endpoint (one containing '/' characters)
-      #
-      # @param endpoint The endpoint to get an addressable URL to.
-      #
-      # @returns The ::Addressable::Template without the endpoint parameter encoded in the URI.
-      #
-      # def get_url_with_special_endpoint(endpoint)
-      #   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 + endpoint
-      #   ::Addressable::Template.new(special_url_string)
-      # end
   end
 end

data/lib/bubbles/version.rb

@@ -5,7 +5,7 @@ module Bubbles
     end
 
     def self.version_name
-      '0.0.8'
+      '0.1.0'
     end
 
     def self.version_code

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bubbles-rest-client
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
 platform: ruby
 authors:
 - Scott Johnson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-19 00:00:00.000000000 Z
+date: 2019-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -165,15 +165,13 @@ files:
 - README.md
 - Rakefile
 - bubbles.gemspec
-- fixtures/vcr_cassettes/get_students_authenticated.yml
-- fixtures/vcr_cassettes/get_version_unauthenticated.yml
 - lib/bubbles.rb
 - lib/bubbles/config.rb
 - lib/bubbles/endpoint.rb
 - lib/bubbles/rest_client_resources.rb
 - lib/bubbles/rest_environment.rb
 - lib/bubbles/version.rb
-homepage: http://www.foamfactorybrewing.com
+homepage: https://github.com/FoamFactory/bubbles
 licenses:
 - MPL-2.0
 metadata:

data/fixtures/vcr_cassettes/get_students_authenticated.yml

@@ -1,46 +0,0 @@
----
-http_interactions:
-- request:
-    method: get
-    uri: http://127.0.0.1:1234/students
-    body:
-      encoding: US-ASCII
-      string: ''
-    headers:
-      Accept:
-      - "*/*"
-      Accept-Encoding:
-      - gzip, deflate
-      User-Agent:
-      - rest-client/2.0.2 (darwin16.1.0 x86_64) ruby/2.4.0p0
-      Authorization:
-      - Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjcmVhdGlvbl9kYXRlIjoiMjAxNy0xMC0xNVQxMToyNjozMS0wNTowMCIsImV4cGlyYXRpb25fZGF0ZSI6IjIwMTctMTEtMTRUMTE6MjY6MzEtMDU6MDAiLCJ1c2VyX2lkIjoxfQ.dyCWwE4wk7aTfjnGncsqp_jq5QyICKYQPkBh5nLQwFU
-      Content-Type:
-      - application/json
-      Host:
-      - 127.0.0.1:1234
-  response:
-    status:
-      code: 200
-      message: OK
-    headers:
-      Content-Type:
-      - application/json; charset=utf-8
-      Etag:
-      - W/"9d4b7d98d38caa096dee4e7844662cf6"
-      Cache-Control:
-      - max-age=0, private, must-revalidate
-      X-Request-Id:
-      - de8e2f1a-4eb7-44a5-9129-84df77d3b938
-      X-Runtime:
-      - '0.014508'
-      Transfer-Encoding:
-      - chunked
-    body:
-      encoding: UTF-8
-      string: '{"students":[{"id":1,"name":"Joe Blow","address":"2234 Bubble Gum Ave.
-        #127","city":"Sometown","state":"CA","zip":"90263","phone":"5558764566","email":"bubblegumbanshee987@bazooka.org","emergencyContactName":"Some
-        Guy","emergencyContactPhone":"5554339182","joinDate":"2017-10-14T00:00:00.000Z","lastAdvancementDate":"2017-10-14T00:00:00.000Z","waiverSigned":true,"created_at":"2017-10-14T21:46:42.826Z","updated_at":"2017-10-14T21:46:42.826Z","preferredContact":"phone","rank":"green"}]}'
-    http_version:
-  recorded_at: Sun, 15 Oct 2017 16:51:12 GMT
-recorded_with: VCR 3.0.3

data/fixtures/vcr_cassettes/get_version_unauthenticated.yml

@@ -1,42 +0,0 @@
----
-http_interactions:
-- request:
-    method: get
-    uri: http://127.0.0.1:1234/version
-    body:
-      encoding: US-ASCII
-      string: ''
-    headers:
-      Accept:
-      - "*/*"
-      Accept-Encoding:
-      - gzip, deflate
-      User-Agent:
-      - rest-client/2.0.2 (darwin16.1.0 x86_64) ruby/2.4.0p0
-      Content-Type:
-      - application/json
-      Host:
-      - 127.0.0.1:1234
-  response:
-    status:
-      code: 200
-      message: OK
-    headers:
-      Content-Type:
-      - application/json; charset=utf-8
-      Etag:
-      - W/"939eb8a8e26be1cdc231493379b6d17c"
-      Cache-Control:
-      - max-age=0, private, must-revalidate
-      X-Request-Id:
-      - fab0bd54-b471-46d4-8f1f-9165c1549c8f
-      X-Runtime:
-      - '0.263693'
-      Transfer-Encoding:
-      - chunked
-    body:
-      encoding: UTF-8
-      string: '{"name":"Sinking Moon API","versionName":"2.0.0","versionCode":8,"deployDate":"2018-01-02T22:51:29-06:00"}'
-    http_version:
-  recorded_at: Wed, 03 Jan 2018 04:51:29 GMT
-recorded_with: VCR 3.0.3