api_client_builder 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a42589201e1aa43a64afa11738378eca1182f7a
-  data.tar.gz: 6c5fea2364dc9e85db7241ea02f9a8d66dced538
+  metadata.gz: 325e44729f05185e293461182fd2f405824ef233
+  data.tar.gz: 44970894a7563a62609223a3efd9b7d38a0ce557
 SHA512:
-  metadata.gz: e6362629e413db828fdfefc719be94de0c10a23a099edf33e136a4a9e2cb7394d7087eb999844a324d89e1b710ddeeb4570914a990a683490bc7659b51f16b17
-  data.tar.gz: f201de0c2a4c149e2958cc772260f9fa0c17c1bdd29c102d3f370043427b647e229342d30a24053eccb88794c58c1656d079f50ff2903190bf85c1a99bd8e66a
+  metadata.gz: edcc960fa01482a12446b8be86a847df5d93a500559901758c410e5cf44d6773e251306b4783821b6b9e9741e10429333a9daaae49da285f937a759b9237e18e
+  data.tar.gz: a9e4eec3e7d812ca887b39324c9fd4ee0d21737d31d8c177df431c40393aea6861aea2936b27a3d0e90a89c0f08849f7e2045b9be56beb1b6a52703294fb310c

data/.dockerignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+sudo: false
+cache: bundler
+rvm:
+  # - ruby-head
+  - 2.1
+  - 2.2
+  - 2.3
+matrix:
+  fast_finish: true
+  # WWTD doesn't support allow_failures... yet
+  # allow_failures:
+  #   - rvm: ruby-head
+script: bundle exec rspec
+notifications:
+  email:
+    on_success: never
+    on_failure: never

data/Dockerfile

@@ -0,0 +1,16 @@
+FROM instructure/rvm
+MAINTAINER Instructure
+
+COPY Gemfile* *.gemspec /usr/src/app/
+COPY lib/api_client_builder/version.rb /usr/src/app/lib/api_client_builder/
+
+USER root
+RUN chown -R docker:docker /usr/src/app
+USER docker
+RUN /bin/bash -l -c "cd /usr/src/app && bundle install"
+
+COPY . /usr/src/app
+USER root
+RUN chown -R docker:docker /usr/src/app/*
+USER docker
+CMD /bin/bash -l -c "cd /usr/src/app && pwd && bundle exec wwtd --parallel"

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Declare your gem's dependencies in logging.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Instructure Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/api_client_builder.gemspec

@@ -8,10 +8,6 @@ Gem::Specification.new do |gem|
   gem.authors       = ['Jayce Higgins']
   gem.email         = ['jhiggins@instructure.com', 'eng@instructure.com']
 
-  gem.files         = %w[api_client_builder.gemspec readme.md]
-
-  gem.test_files    = Dir.glob("spec/**/*")
-  gem.require_paths = ["lib"]
   gem.version       = APIClientBuilder::VERSION
   gem.required_ruby_version = '>= 2.0'
 
@@ -20,4 +16,9 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'pry'
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'wwtd'
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  gem.require_paths = ["lib"]
 end

data/build.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+docker-compose build --pull
+docker-compose run test

data/docker-compose.yml

@@ -0,0 +1,4 @@
+test:
+  build: .
+  volumes:
+    - "coverage:/app/coverage"

data/lib/api_client_builder.rb

@@ -0,0 +1,9 @@
+require 'api_client_builder/version'
+require 'api_client_builder/api_client'
+require 'api_client_builder/get_collection_request'
+require 'api_client_builder/get_item_request'
+require 'api_client_builder/post_request'
+require 'api_client_builder/put_request'
+require 'api_client_builder/request'
+require 'api_client_builder/response'
+require 'api_client_builder/url_generator'

data/lib/api_client_builder/api_client.rb

@@ -0,0 +1,85 @@
+require 'api_client_builder/get_collection_request'
+require 'api_client_builder/get_item_request'
+require 'api_client_builder/post_request'
+require 'api_client_builder/put_request'
+require 'api_client_builder/url_generator'
+
+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
+  end
+end

data/lib/api_client_builder/get_collection_request.rb

@@ -0,0 +1,43 @@
+require 'api_client_builder/request'
+
+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
+    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
+
+    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,29 @@
+require 'api_client_builder/request'
+
+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,21 @@
+require 'api_client_builder/request'
+
+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,21 @@
+require 'api_client_builder/request'
+
+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?
+        self.on_error do |page, handler|
+          raise 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: #{page.status_code}"
+        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,39 @@
+require 'uri'
+
+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('/').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}", 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.0.1' unless defined?(APIClientBuilder::VERSION)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_client_builder
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Jayce Higgins
@@ -61,8 +61,27 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .dockerignore
+- .gitignore
+- .travis.yml
+- Dockerfile
+- Gemfile
+- LICENSE.txt
+- README.md
+- api_client_builder-1.0.0.gem
 - api_client_builder.gemspec
-- readme.md
+- build.sh
+- docker-compose.yml
+- lib/api_client_builder.rb
+- lib/api_client_builder/api_client.rb
+- lib/api_client_builder/get_collection_request.rb
+- lib/api_client_builder/get_item_request.rb
+- lib/api_client_builder/post_request.rb
+- lib/api_client_builder/put_request.rb
+- lib/api_client_builder/request.rb
+- lib/api_client_builder/response.rb
+- lib/api_client_builder/url_generator.rb
+- lib/api_client_builder/version.rb
 - spec/lib/api_client_builder/api_client_spec.rb
 - spec/lib/api_client_builder/get_collection_request_spec.rb
 - spec/lib/api_client_builder/get_item_request_spec.rb