api_client_builder 1.0.0 → 1.4.0

data/lib/api_client_builder/api_client.rb

@@ -0,0 +1,96 @@
+module APIClientBuilder
+  # The base APIClient that defines the interface for defining an API Client.
+  # Should be sub-classed and then provided an HTTPClient handler and a
+  # response handler.
+  class APIClient
+    attr_reader :url_generator, :http_client
+
+    # @param opts [Hash] options hash
+    # @option opts [Symbol] :http_client The http client handler
+    # @option opts [Symbol] :paginator The response handler
+    def initialize(**opts)
+      @url_generator = APIClientBuilder::URLGenerator.new(opts[:domain])
+      @http_client = opts[:http_client]
+    end
+
+    # Used to define a GET api route on the base class. Will
+    # yield a method that takes the shape of 'get_type' that will
+    # return a CollectionResponse or ItemResponse based on plurality.
+    #
+    # @param type [Symbol] defines the route model
+    # @param plurality [Symbol] defines the routes plurality
+    # @param route [String] defines the routes endpoint
+    #
+    # @return [Request] either a GetCollection or GetItem request
+    def self.get(type, plurality, route, **_opts)
+      if plurality == :collection
+        define_method("get_#{type}") do |**params|
+          GetCollectionRequest.new(
+            type,
+            response_handler_build(http_client, @url_generator.build_route(route, **params), type)
+          )
+        end
+      elsif plurality == :singular
+        define_method("get_#{type}") do |**params|
+          GetItemRequest.new(
+            type,
+            response_handler_build(http_client, @url_generator.build_route(route, **params), type)
+          )
+        end
+      end
+    end
+
+    # Used to define a POST api route on the base class. Will
+    # yield a method that takes the shape of 'post_type' that will
+    # return a PostRequest.
+    #
+    # @param type [Symbol] defines the route model
+    # @param route [String] defines the routes endpoint
+    #
+    # @return [PostRequest] the request object that handles posts
+    def self.post(type, route)
+      define_method("post_#{type}") do |body, **params|
+        PostRequest.new(
+          type,
+          response_handler_build(http_client, @url_generator.build_route(route, **params), type),
+          body
+        )
+      end
+    end
+
+    # Used to define a PUT api route on the base class. Will
+    # yield a method that takes the shape of 'put_type' that will
+    # return a PutRequest.
+    #
+    # @param type [Symbol] defines the route model
+    # @param route [String] defines the routes endpoint
+    #
+    # @return [PutRequest] the request object that handles puts
+    def self.put(type, route)
+      define_method("put_#{type}") do |body, **params|
+        PutRequest.new(
+          type,
+          response_handler_build(http_client, @url_generator.build_route(route, **params), type),
+          body
+        )
+      end
+    end
+
+    # Used to define a DELETE api route on the base class. Will
+    # yield a method that takes the shape of 'delete_type' that will
+    # return a DeleteRequest.
+    #
+    # @param type [Symbol] defines the route model
+    # @param route [String] defines the routes endpoint
+    #
+    # @return [DeleteRequest] the request object that handles puts
+    def self.delete(type, route)
+      define_method("delete_#{type}") do |**params|
+        DeleteRequest.new(
+          type,
+          response_handler_build(http_client, @url_generator.build_route(route, **params), type)
+        )
+      end
+    end
+  end
+end

data/lib/api_client_builder/delete_request.rb

@@ -0,0 +1,19 @@
+module APIClientBuilder
+  class DeleteRequest < Request
+    # Yields the response body if the response was successful. Will call
+    # the response handlers if there was not a successful response.
+    #
+    # @return [JSON] the http response body
+    def response
+      response = response_handler.delete_request
+
+      if response.success?
+        response
+      else
+        error_handlers.each do |handler|
+          handler.call(response, self)
+        end
+      end
+    end
+  end
+end

data/lib/api_client_builder/get_collection_request.rb

@@ -0,0 +1,43 @@
+module APIClientBuilder
+  # The multi item response object to be used as the container for
+  # collection responses from the defined API
+  class GetCollectionRequest < Request
+    include Enumerable
+
+    # Iterates over the pages and yields their items if they're successful
+    # responses. Else handles the error. Will retry the response if a retry
+    # strategy is defined concretely on the response handler.
+    #
+    # @return [JSON] the http response body
+    # rubocop:disable Metrics/AbcSize
+    def each
+      if block_given?
+        each_page do |page|
+          if page.success?
+            page.body.each do |item|
+              yield(item)
+            end
+          elsif response_handler.respond_to?(:retryable?) && response_handler.retryable?(page.status_code)
+            retried_page = attempt_retry
+
+            retried_page.body.each do |item|
+              yield(item)
+            end
+          else
+            notify_error_handlers(page)
+          end
+        end
+      else
+        Enumerator.new(self, :each)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    private
+
+    def each_page
+      yield(response_handler.get_first_page)
+      yield(response_handler.get_next_page) while response_handler.more_pages?
+    end
+  end
+end

data/lib/api_client_builder/get_item_request.rb

@@ -0,0 +1,27 @@
+module APIClientBuilder
+  # The single item response object to be used as the container for
+  # singular responses from the defined API
+  class GetItemRequest < Request
+    # Reads the first page from the pagination solution and yields the
+    # items if the response was successful. Else handles the error. Will
+    # retry the response if a retry strategy is defined concretely on the
+    # response handler.
+    #
+    # @return [JSON] the http response body
+    def response
+      page = response_handler.get_first_page
+
+      if page.success?
+        page.body
+      elsif response_handler.respond_to?(:retryable?) && response_handler.retryable?(page.status_code)
+        retried_page = attempt_retry
+
+        retried_page.body
+      else
+        error_handlers.each do |handler|
+          handler.call(page, self)
+        end
+      end
+    end
+  end
+end

data/lib/api_client_builder/post_request.rb

@@ -0,0 +1,19 @@
+module APIClientBuilder
+  class PostRequest < Request
+    # Yields the response body if the response was successful. Will call
+    # the response handlers if there was not a successful response.
+    #
+    # @return [JSON] the http response body
+    def response
+      response = response_handler.post_request(@body)
+
+      if response.success?
+        response
+      else
+        error_handlers.each do |handler|
+          handler.call(response, self)
+        end
+      end
+    end
+  end
+end

data/lib/api_client_builder/put_request.rb

@@ -0,0 +1,19 @@
+module APIClientBuilder
+  class PutRequest < Request
+    # Yields the response body if the response was successful. Will call
+    # the response handlers if there was not a successful response.
+    #
+    # @return [JSON] the http response body
+    def response
+      response = response_handler.put_request(@body)
+
+      if response.success?
+        response
+      else
+        error_handlers.each do |handler|
+          handler.call(response, self)
+        end
+      end
+    end
+  end
+end

data/lib/api_client_builder/request.rb

@@ -0,0 +1,66 @@
+module APIClientBuilder
+  class DefaultPageError < StandardError; end
+
+  class Request
+    attr_reader :type, :response_handler, :body, :error_handlers_collection
+
+    # @param type [Symbol] defines the object type to be processed
+    # @option response_handler [ResponseHandler] the response handler. Usually
+    # a pagination strategy
+    # @option body [Hash] the body of the response from the source
+    def initialize(type, response_handler, body = {})
+      @type = type
+      @response_handler = response_handler
+      @body = body
+      @error_handlers_collection = []
+    end
+
+    # Yields the collection of error handlers that have been populated
+    # via the on_error interface. If none are defined, this will provide a
+    # default error handler that will provide context about the error and
+    # also how to define a new error handler.
+    #
+    # @return [Array<Block>] the error handlers collection
+    def error_handlers
+      if error_handlers_collection.empty?
+        on_error do |page, _handler|
+          raise DefaultPageError, <<~MESSAGE
+            Default error for bad response. If you want to handle this error use #on_error
+            on the response in your api consumer. Error Code: #{page.status_code}.
+          MESSAGE
+        end
+      end
+      error_handlers_collection
+    end
+
+    # Used to define custom error handling on this response.
+    # The error handlers will be called if there is not a success
+    #
+    # @param block [Lambda] the error handling block to be stored in
+    #   the error_handlers list
+    def on_error(&block)
+      @error_handlers_collection << block
+    end
+
+    private
+
+    def attempt_retry
+      page = response_handler.retry_request
+
+      if page.success?
+        response_handler.reset_retries
+        return page
+      elsif response_handler.retryable?(page.status_code)
+        attempt_retry
+      else
+        notify_error_handlers(page)
+      end
+    end
+
+    def notify_error_handlers(page)
+      error_handlers.each do |handler|
+        handler.call(page, self)
+      end
+    end
+  end
+end

data/lib/api_client_builder/response.rb

@@ -0,0 +1,32 @@
+module APIClientBuilder
+  # The default page object to be used to hold the response from the API
+  # in your response handler object. Any response object that will replace this
+  # must response to #success?, and #items
+  class Response
+    attr_accessor :body, :status_code
+
+    # @param body [String/Array/Hash] the response body
+    # @param status_code [Integer] the response status code
+    # @param success_range [Array<Integer>] the success range of this response
+    def initialize(body, status_code, success_range)
+      @body = body
+      @status_code = status_code
+      @success_range = success_range
+      @failed_reason = nil
+    end
+
+    # Used to mark why the response failed
+    def mark_failed(reason)
+      @failed_reason = reason
+    end
+
+    # Defines the success conditional for a response by determining whether
+    # or not the status code of the response is within the defined success
+    # range
+    #
+    # @return [Boolean] whether or not the response is a success
+    def success?
+      @failed_reason.nil? && @success_range.include?(@status_code)
+    end
+  end
+end

data/lib/api_client_builder/url_generator.rb

@@ -0,0 +1,37 @@
+module APIClientBuilder
+  class NoURLError < StandardError; end
+  class URLGenerator
+    # Receives a domain and parses it into a URI
+    #
+    # @param domain [String] the domain of the API
+    def initialize(domain)
+      @base_uri = URI.parse(domain)
+      @base_uri = URI.parse('https://' + domain) if @base_uri.scheme.nil?
+      @base_uri.path << '/' unless @base_uri.path.end_with?('/')
+    end
+
+    # Defines a full API route and interpolates parameters into the route
+    # provided that the parameter sent in has a key that matches the parameter
+    # that is defined by the route.
+    #
+    # @param route [String] defines the route endpoint
+    # @param params [Hash] the optional params to be interpolated into the route
+    #
+    # @raise [ArgumentError] if route defined param is not provided
+    #
+    # @return [URI] the fully built route
+    def build_route(route, **params)
+      string_params = route.split(%r{[\/=]}).select { |param| param.start_with?(':') }
+      symboled_params = string_params.map { |param| param.tr(':', '').to_sym }
+
+      new_route = route.clone
+      symboled_params.each do |param|
+        value = params[param]
+        raise ArgumentError, "Param :#{param} is required" unless value
+        new_route.gsub!(":#{param}", CGI.escape(value.to_s))
+      end
+
+      @base_uri.merge(new_route)
+    end
+  end
+end

data/lib/api_client_builder/version.rb

@@ -0,0 +1,3 @@
+module APIClientBuilder
+  VERSION = '1.4.0'.freeze
+end

data/spec/lib/api_client_builder/api_client_spec.rb

@@ -1,11 +1,10 @@
 require 'spec_helper'
-require 'lib/api_client_builder/test_client/client'
-require 'api_client_builder/api_client'
+require_relative 'test_client/client'
 
 module APIClientBuilder
   describe APIClient do
-    let(:domain) {'https://www.domain.com/api/endpoints/'}
-    let(:client) {TestClient::Client.new(domain: domain)}
+    let(:domain) { 'https://www.domain.com/api/endpoints/' }
+    let(:client) { TestClient::Client.new(domain: domain) }
 
     describe '.get' do
       context 'plurality is :collection' do
@@ -42,5 +41,15 @@ module APIClientBuilder
         expect(client.put_some_object({})).to be_a(APIClientBuilder::PutRequest)
       end
     end
+
+    describe '.delete' do
+      it 'defines a delete method on the client' do
+        expect(client).to respond_to(:delete_some_object)
+      end
+
+      it 'returns a DeleteRequest object' do
+        expect(client.delete_some_object({})).to be_a(APIClientBuilder::DeleteRequest)
+      end
+    end
   end
 end

data/spec/lib/api_client_builder/delete_request_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+require_relative 'test_client/client'
+
+module APIClientBuilder
+  describe DeleteRequest do
+    describe '#response' do
+      context 'request was successful' do
+        it 'returns a response object' do
+          client = TestClient::Client.new(domain: 'https://www.domain.com/api/endpoints/')
+
+          some_object = client.delete_some_object({}).response
+          expect(some_object.body).to eq('good delete request')
+        end
+      end
+
+      context 'request was unsuccessful' do
+        it 'calls the error handlers' do
+          client = TestClient::Client.new(domain: 'https://www.domain.com/api/endpoints/')
+
+          bad_response = APIClientBuilder::Response.new('bad request', 400, [200])
+          allow_any_instance_of(TestClient::ResponseHandler).to receive(:delete_request).and_return(bad_response)
+          expect { client.delete_some_object({}).response }.to raise_error(
+            APIClientBuilder::DefaultPageError, /Error Code: 400/
+          )
+        end
+      end
+    end
+  end
+end

data/spec/lib/api_client_builder/get_collection_request_spec.rb

@@ -1,6 +1,5 @@
 require 'spec_helper'
-require 'api_client_builder/get_collection_request'
-require 'lib/api_client_builder/test_client/client'
+require_relative 'test_client/client'
 
 module APIClientBuilder
   describe GetCollectionRequest do
@@ -21,9 +20,8 @@ module APIClientBuilder
           bad_response = APIClientBuilder::Response.new('bad request', 500, [200])
           allow_any_instance_of(TestClient::ResponseHandler).to receive(:get_first_page).and_return(bad_response)
           allow_any_instance_of(TestClient::ResponseHandler).to receive(:retry_request).and_return(bad_response)
-          expect{ client.get_some_objects.each{} }.to raise_error(
-            APIClientBuilder::DefaultPageError,
-            "Default error for bad response. If you want to handle this error use #on_error on the response in your api consumer. Error Code: 500"
+          expect { client.get_some_objects.each {} }.to raise_error(
+            APIClientBuilder::DefaultPageError, /Error Code: 500/
           )
         end
 
@@ -32,7 +30,7 @@ module APIClientBuilder
             client = TestClient::Client.new(domain: 'https://www.domain.com/api/endpoints/')
 
             bad_response = APIClientBuilder::Response.new('bad request', 500, [200])
-            good_response = APIClientBuilder::Response.new([1,2,3], 200, [200])
+            good_response = APIClientBuilder::Response.new([1, 2, 3], 200, [200])
             allow_any_instance_of(TestClient::ResponseHandler).to receive(:get_first_page).and_return(bad_response)
             allow_any_instance_of(TestClient::ResponseHandler).to receive(:more_pages?).and_return(false)
             allow_any_instance_of(TestClient::ResponseHandler).to receive(:retry_request).and_return(good_response)
@@ -47,13 +45,12 @@ module APIClientBuilder
             client = TestClient::Client.new(domain: 'https://www.domain.com/api/endpoints/')
 
             bad_response = APIClientBuilder::Response.new('bad request', 400, [200])
-            good_response = APIClientBuilder::Response.new([1,2,3], 200, [200])
+            good_response = APIClientBuilder::Response.new([1, 2, 3], 200, [200])
             allow_any_instance_of(TestClient::ResponseHandler).to receive(:get_first_page).and_return(bad_response)
             allow_any_instance_of(TestClient::ResponseHandler).to receive(:more_pages?).and_return(false)
             allow_any_instance_of(TestClient::ResponseHandler).to receive(:retry_request).and_return(good_response)
-            expect{ client.get_some_objects.each{} }.to raise_error(
-              APIClientBuilder::DefaultPageError,
-              "Default error for bad response. If you want to handle this error use #on_error on the response in your api consumer. Error Code: 400"
+            expect { client.get_some_objects.each {} }.to raise_error(
+              APIClientBuilder::DefaultPageError, /Error Code: 400/
             )
           end
         end