bubbles-rest-client 0.3.1 → 0.7.0

data/lib/bubbles/config.rb

@@ -10,7 +10,7 @@ module Bubbles
   ##
   # Configure the Bubbles instance.
   #
-  # Use this method if you want to configure the Bubbles instance, typically during intialization of your Gem or
+  # Use this method if you want to configure the Bubbles instance, typically during initialization of your Gem or
   # application.
   #
   # @example In app/config/initializers/bubbles.rb
@@ -39,42 +39,85 @@ module Bubbles
   #
   class Configuration
     def initialize
-      @environment_scheme = 'http'
-      @environment_host = '127.0.0.1'
-      @environment_port = '1234'
-      @environment_api_key = nil
-
+      @environments = Hash.new
       @endpoints = Hash.new
     end
 
     ##
-    # Retrieve the {RestEnvironment} object defined as part of this Configuration.
+    # Retrieve the {RestEnvironment} object defined as part of this Configuration having a specified name.
+    #
+    # @param [String] environment_name The name of the {RestEnvironment} to retrieve.
+    #
+    # The +environment_name+ is +nil+ by default, which will return the default configuration, if only one exists.
     #
-    # Note that this constructs a new +RestEnvironment+ and returns it, rather than returning an existing object.
+    # @return [RestEnvironment] A new +RestEnvironment+ having the configuration that was created with key
+    #         +environment_name+. Note that +RestEnvironment+s are essentially immutable once they are created, so
+    #         an existing object will _never_ be returned.
     #
-    def environment
-      RestEnvironment.new(@environment_scheme, @environment_host, @environment_port, @environment_api_key)
+    def environment(environment_name = nil)
+      if environment_name.nil?
+        if @environments.length > 1
+          raise 'You must specify an environment_name parameter because more than one environment is defined'
+        end
+
+        env_hash = @environments[nil]
+      else
+        env_hash = @environments[environment_name]
+      end
+
+      if env_hash.nil?
+        if environment_name.nil?
+          raise 'No default environment specified'
+        end
+
+        raise 'No environment specified having name {}', environment_name
+      end
+
+      RestEnvironment.new(env_hash[:scheme], env_hash[:host], env_hash[:port], env_hash[:api_key],
+                          env_hash[:api_key_name])
     end
 
     ##
-    # Set the current environment.
+    # Set the environments that can be used.
     #
-    # @param [Object] env The environment, as a generic Ruby Object.
+    # @param [Array] environments The environments, as an array with each entry a +Hash+.
+    #
+    # One or more environments may be specified, but if more than one environment is specified, it is required that each
+    # environment have a +:environment_name:+ parameter to differentiate it from other environments.
     #
     # @example In app/config/environments/staging.rb:
     #    Bubbles.configure do |config|
-    #      config.environment = {
+    #      config.environments = [{
     #         :scheme => 'https',
     #         :host => 'stage.api.somehost.com',
-    #         :port => '443'
-    #      }
+    #         :port => '443',
+    #         :api_key => 'something',
+    #         :api_key_name => 'X-API-Key' # Optional
+    #      }]
     #    end
     #
-    def environment=(env)
-      @environment_scheme = env[:scheme]
-      @environment_host = env[:host]
-      @environment_port = env[:port]
-      @environment_api_key = env[:api_key]
+    def environments=(environments)
+      default = nil
+      environments.each do |environment|
+        if environments.length > 1 && environment[:environment_name].nil?
+          message = 'More than one environment was specified and at least one of the environments does not have an ' \
+                    ':environment_name field. Verify all environments have an :environment_name.'
+
+          raise message
+        end
+
+        @environments = {}
+        env_api_key = 'X-API-Key'
+        env_api_key = environment[:api_key_name] if environment.key? :api_key_name
+
+        @environments[environment[:environment_name]] = {
+          scheme: environment[:scheme],
+          host: environment[:host],
+          port: environment[:port],
+          api_key: environment[:api_key],
+          api_key_name: env_api_key
+        }
+      end
     end
 
     ##
@@ -103,7 +146,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], ep[:return_type], ep[:encode_authorization]
+        endpoint_object = Endpoint.new ep[:method], ep[:location].to_s, ep[:authenticated], ep[:api_key_required], ep[:name], ep[:return_type], ep[:encode_authorization], ep[:headers]
 
         new_endpoints[endpoint_object.get_key_string] = endpoint_object
       end
@@ -128,99 +171,113 @@ module Bubbles
           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_get_authenticated self, endpoint, auth_token, uri_params
+                if endpoint.encode_authorization_header?
+                  define_method(endpoint_name_as_sym) do |username, password, uri_params|
+                    login_data = {
+                      :login => username,
+                      :password => password
+                    }
+                    auth_value = RestClientResources.get_encoded_authorization(endpoint, login_data)
+                    RestClientResources.execute_get_authenticated self, endpoint, :basic, auth_value, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                  end
+                else
+                  define_method(endpoint_name_as_sym) do |auth_token, uri_params|
+                    RestClientResources.execute_get_authenticated self, endpoint, :bearer, auth_token, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                  end
                 end
               else
-                define_method(endpoint_name_as_sym) do |auth_token|
-                  RestClientResources.execute_get_authenticated self, endpoint, auth_token, {}
+                if endpoint.encode_authorization_header?
+                  define_method(endpoint_name_as_sym) do |username, password|
+                    login_data = {
+                      :username => username,
+                      :password => password
+                    }
+                    auth_value = RestClientResources.get_encoded_authorization(endpoint, login_data)
+
+                    RestClientResources.execute_get_authenticated self, endpoint, :basic, auth_value, {}, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                  end
+                else
+                  define_method(endpoint_name_as_sym) do |auth_token|
+                    RestClientResources.execute_get_authenticated self, endpoint, :bearer, auth_token, {}, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                  end
                 end
               end
             end
           else
             Bubbles::RestEnvironment.class_exec do
-              define_method(endpoint_name_as_sym) do
-                RestClientResources.execute_get_unauthenticated self, endpoint
+              if endpoint.has_uri_params?
+                define_method(endpoint_name_as_sym) do |uri_params|
+                  RestClientResources.execute_get_unauthenticated self, endpoint, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                end
+              else
+                define_method(endpoint_name_as_sym) do
+                  RestClientResources.execute_get_unauthenticated self, endpoint, {}, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                end
               end
             end
           end
         elsif endpoint.method == :post
-          if endpoint.authenticated?
+          if endpoint.authenticated? and !endpoint.encode_authorization_header?
             Bubbles::RestEnvironment.class_exec do
               define_method(endpoint_name_as_sym) do |auth_token, data|
-                RestClientResources.execute_post_authenticated self, endpoint, auth_token, data
+                RestClientResources.execute_post_authenticated self, endpoint, :bearer, auth_token, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
               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
+          elsif endpoint.encode_authorization_header?
+            Bubbles::RestEnvironment.class_exec do
+              define_method(endpoint_name_as_sym) do |username, password, data = {}|
+                login_data = {
+                  :username => username,
+                  :password => password
+                }
 
-                  RestClientResources.execute_post_with_api_key self, endpoint, self.api_key, data, additional_headers
-                end
+                auth_value = RestClientResources.get_encoded_authorization(endpoint, login_data)
+                # composite_headers = RestClientResources.build_composite_headers(endpoint.additional_headers, {
+                #                                                                   Authorization: 'Basic ' + Base64.strict_encode64(auth_value)
+                #                                                                 })
+                RestClientResources.execute_post_authenticated self, endpoint, :basic, auth_value, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+              end
+            end
+          else
+            Bubbles::RestEnvironment.class_exec do
+              define_method(endpoint_name_as_sym) do |data|
+                composite_headers = endpoint.additional_headers
+                RestClientResources.execute_post_unauthenticated self, endpoint, data, composite_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
               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?
+          if endpoint.has_uri_params?
+            if endpoint.authenticated?
+              Bubbles::RestEnvironment.class_exec do
                 define_method(endpoint_name_as_sym) do |auth_token, uri_params|
-                  RestClientResources.execute_delete_authenticated self, endpoint, auth_token, uri_params
+                  RestClientResources.execute_delete_authenticated self, endpoint, auth_token, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
+                end
+              end
+            else
+              Bubbles::RestEnvironment.class_exec do
+                define_method(endpoint_name_as_sym) do |uri_params|
+                  RestClientResources.execute_delete_unauthenticated self, endpoint, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 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
+            # XXX_jwir3: 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. In addition, RestClient doesn't seem to support DELETE
+            # requests with a body, so we're a bit stuck on this one, even if we wanted to support it.
+            raise 'DELETE requests without URI parameters are not allowed'
           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
+                  RestClientResources.execute_patch_authenticated self, endpoint, auth_token, uri_params, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               else
                 define_method(endpoint_name_as_sym) do |auth_token, data|
-                  # TODO: Nothing tests this case. We need something to test this case or we run the risk of
-                  #       it having bugs (uri_params was nil previously!)
-                  RestClientResources.execute_patch_authenticated self, endpoint, auth_token, {}, data
+                  RestClientResources.execute_patch_authenticated self, endpoint, auth_token, {}, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               end
             end
@@ -228,11 +285,11 @@ module Bubbles
             Bubbles::RestEnvironment.class_exec do
               if endpoint.has_uri_params?
                 define_method(endpoint_name_as_sym) do |uri_params, data|
-                  RestClientResources.execute_patch_unauthenticated self, endpoint, uri_params, data
+                  RestClientResources.execute_patch_unauthenticated self, endpoint, uri_params, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               else
                 define_method(endpoint_name_as_sym) do |data|
-                  RestClientResources.execute_patch_unauthenticated self, endpoint, {}, data
+                  RestClientResources.execute_patch_unauthenticated self, endpoint, {}, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               end
             end
@@ -242,26 +299,23 @@ module Bubbles
             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
+                  RestClientResources.execute_put_authenticated self, endpoint, auth_token, uri_params, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               else
                 define_method(endpoint_name_as_sym) do |auth_token, data|
-                  # TODO: Nothing tests this case. We need something to test this case or we run the risk of
-                  #       it having bugs (uri_params was nil previously!)
-                  RestClientResources.execute_put_authenticated self, endpoint, auth_token, {}, data
+                  RestClientResources.execute_put_authenticated self, endpoint, auth_token, {}, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               end
             end
           else
-            # raise 'Unauthenticated PUT requests are not implemented'
             Bubbles::RestEnvironment.class_exec do
               if endpoint.has_uri_params?
                 define_method(endpoint_name_as_sym) do |uri_params, data|
-                  RestClientResources.execute_put_unauthenticated self, endpoint, uri_params, data
+                  RestClientResources.execute_put_unauthenticated self, endpoint, uri_params, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               else
                 define_method(endpoint_name_as_sym) do |data|
-                  RestClientResources.execute_put_unauthenticated self, endpoint, {}, data
+                  RestClientResources.execute_put_unauthenticated self, endpoint, {}, data, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               end
             end
@@ -271,23 +325,11 @@ module Bubbles
             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
+                  RestClientResources.execute_head_authenticated self, endpoint, auth_token, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 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 |uri_params|
-                  RestClientResources.execute_head_unauthenticated_with_uri_params self, endpoint, self.api_key, uri_params
-                end
-              else
-                define_method(endpoint_name_as_sym) do
-                  RestClientResources.execute_head_unauthenticated self, endpoint, self.api_key, nil
+                  RestClientResources.execute_head_authenticated self, endpoint, auth_token, {}, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               end
             end
@@ -295,11 +337,11 @@ module Bubbles
             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, {}
+                  RestClientResources.execute_head_unauthenticated self, endpoint, uri_params, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               else
                 define_method(endpoint_name_as_sym) do
-                  RestClientResources.execute_head_unauthenticated self, endpoint, {}, {}
+                  RestClientResources.execute_head_unauthenticated self, endpoint, {}, endpoint.additional_headers, self.get_api_key_if_needed(endpoint), self.api_key_name
                 end
               end
             end

data/lib/bubbles/endpoint.rb

@@ -74,13 +74,14 @@ module Bubbles
     # @param [Array<Symbol>] encode_authorization Parameters that should be treated as authorization parameters and
     #        encoded using a Base64 encoding.
     #
-    def initialize(method, location, auth_required = false, api_key_required = false, name = nil, return_type = :body_as_string, encode_authorization = {})
+    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
@@ -145,13 +146,10 @@ module Bubbles
     #
     # @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}.
+    # @return [Addressable::URI] An +Addressable::URI+ containing the full URL to access this +Endpoint+ on the given
+    #         +RestEnvironment+.
     #
     def get_expanded_url(env, uri_params = {})
-      unless uri_params
-        uri_params = {}
-      end
-
       url = get_base_url env
 
       if is_complex?
@@ -239,7 +237,7 @@ module Bubbles
     #         for the +Endpoint+, to be defined on {RestClientResources}; false, otherwise.
     #
     def name?
-      @name == nil
+      @name != nil
     end
 
     ##
@@ -272,5 +270,17 @@ module Bubbles
     def has_uri_params?
       !@uri_params.empty?
     end
+
+    def additional_headers
+      unless @additional_headers
+        @additional_headers = {}
+      end
+
+      @additional_headers
+    end
+
+    def has_additional_headers?
+      not additional_headers.empty?
+    end
   end
 end