api_client_builder 1.0.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6a42589201e1aa43a64afa11738378eca1182f7a
-  data.tar.gz: 6c5fea2364dc9e85db7241ea02f9a8d66dced538
+SHA256:
+  metadata.gz: 61488aa64b23c4e971039af08754ac43a70277fe13cdb14ec5cc95cdc2cb4c1a
+  data.tar.gz: 1a14eaed9a3b913023c76e7b9788a3f8f39dea98749d299283eb5fe11d2a9d96
 SHA512:
-  metadata.gz: e6362629e413db828fdfefc719be94de0c10a23a099edf33e136a4a9e2cb7394d7087eb999844a324d89e1b710ddeeb4570914a990a683490bc7659b51f16b17
-  data.tar.gz: f201de0c2a4c149e2958cc772260f9fa0c17c1bdd29c102d3f370043427b647e229342d30a24053eccb88794c58c1656d079f50ff2903190bf85c1a99bd8e66a
+  metadata.gz: 6b0431c58dff83f80caffcd891a7b984982143cc829403b1b49b97889570a452ea6df1d3b216fc1d2d76e68599d2ba1f3add4101eaca2402727e3d9ddbb274ec
+  data.tar.gz: b717e8415fc64ffbe9de0eb2c8086c282d87b943577e1e4d5bf6e84b620594ad6de9b3ac0e89a6ac3e79c570ff4cd72d08be854ffa8dc4d819ca843d4b17be42

data/.gitignore

@@ -0,0 +1,3 @@
+/coverage
+/Gemfile.lock
+/*.gem

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  TargetRubyVersion: 2.3
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+
+Metrics/LineLength:
+  Max: 120 # Default: 80
+
+Metrics/MethodLength:
+  Max: 20 # Default: 10
+
+Naming/AccessorMethodName: # TODO: Enable and fix API at some point.
+  Enabled: false
+
+Style/Documentation:
+  # This cop checks for missing top-level documentation of classes and modules.
+  # Classes with no body and namespace modules are exempt from the check.
+  # Namespace modules are modules that have nothing in their bodies except
+  # classes or other modules.
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  # `when_needed` will add the frozen string literal comment to files
+  # only when the `TargetRubyVersion` is set to 2.3+.
+  # `always` will always add the frozen string literal comment to a file
+  # regardless of the Ruby version or if `freeze` or `<<` are called on a
+  # string literal. If you run code against multiple versions of Ruby, it is
+  # possible that this will create errors in Ruby 2.3.0+.
+  #
+  # See: https://wyeworks.com/blog/2015/12/1/immutable-strings-in-ruby-2-dot-3
+  EnforcedStyle: when_needed
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,20 @@
+dist: trusty
+sudo: false
+language: ruby
+cache: bundler
+
+rvm:
+  - 2.3
+  - 2.4
+  - 2.5
+
+matrix:
+  fast_finish: true
+
+before_install: gem update bundler
+bundler_args: --jobs 3
+install: bundle install --jobs 3
+
+script:
+  - bundle exec rubocop --fail-level autocorrect
+  - bundle exec rspec

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/Jenkinsfile

@@ -0,0 +1,13 @@
+pipeline {
+  agent {
+    label 'docker'
+  }
+
+  stages {
+    stage('Lint & Test') {
+      steps {
+        sh './build.sh'
+      }
+    }
+  }
+}

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016-2018 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/{readme.md → README.md}

@@ -3,7 +3,9 @@
 API Client Builder was created to reduce the overhead of creating API clients.
 
 It provides a DSL for defining endpoints and only requires you to define handlers
-for http requests and responses.
+for HTTP requests and responses.
+
+[![Build Status](https://travis-ci.org/instructure/api-client-builder.svg?branch=master)](https://travis-ci.org/instructure/api-client-builder)
 
 ---
 
@@ -28,10 +30,6 @@ Or install it yourself as:
 The basic client structure looks like this.
 
 ```ruby
-require 'api_client_builder/api_client'
-require 'path/to/your/http_client_handler'
-require 'path/to/your/response_handler'
-
 class Client < APIClientBulder::APIClient
   def initialize(**opts)
     super(domain: opts[:domain],
@@ -55,8 +53,8 @@ def response_handler_build(http_client, start_url, type)
 end
 ```
 
-
 ### Defining routes on the client
+
 To define routes on the api client, use the DSL provided by the
 builder's APIClient class. Four parts have been defined to help:
 
@@ -81,7 +79,6 @@ builder's APIClient class. Four parts have been defined to help:
   - Note that any symbols in the route will be interpolated as required
    params when calling the method on the client.
 
-
 ---
 
 ## Route Examples
@@ -91,7 +88,7 @@ builder's APIClient class. Four parts have been defined to help:
 Define the route on the client
 
 ```ruby
-  get :some_object, :singular, 'some_objects/:id'
+get :some_object, :singular, 'some_objects/:id'
 ```
 
 Use the defined route
@@ -107,7 +104,7 @@ response_body = single_request.response
 Define the route on the client
 
 ```ruby
-  get :some_objects, :collection, 'some_objects'
+get :some_objects, :collection, 'some_objects'
 ```
 
 Use the defined route
@@ -116,7 +113,7 @@ Use the defined route
 collection_request = client.get_some_objects
 
 collection_request.each do |item|
-  #Item will be a Hash if you use the default response in the response handler
+  # Item will be a Hash if you use the default response in the response handler
 end
 ```
 
@@ -166,16 +163,16 @@ get :some_objects_for_course, :collection, 'course/:course_id/some_objects'
 
 ## Defining an HTTP Client Handler
 
-The HTTP Client Handler is designed to manage the http requests themselves. Since
+The HTTP Client Handler is designed to manage the HTTP requests themselves. Since
 actually making an HTTP request typically requires some amount of authentication,
 it is suggested that authentication and headers are managed here as well.
 
-The http client handler requires '#get', '#post', and '#put' to be defined here
+The HTTP client handler requires '#get', '#post', and '#put' to be defined here
 with the shown method signature.
 
 ```ruby
 class HTTPClientHandler
-  #Do initialization here, generally authentication creds and a domain is sent in
+  # Do initialization here, generally authentication creds and a domain is sent in
 
   def get(route, params = nil, headers = {})
     client.get(route, params, headers)
@@ -189,9 +186,13 @@ class HTTPClientHandler
     client.post(route, params, headers)
   end
 
-  #Define a client to use here. The HTTPClient gem is a good option
+  def delete(route, params = nil, headers = {})
+    client.delete(route, params, headers)
+  end
+
+  # Define a client to use here. The HTTPClient gem is a good option
 
-  #Build up headers and authentication handling here as well
+  # Build up headers and authentication handling here as well
 end
 ```
 
@@ -219,11 +220,11 @@ these actions simpler.
 
 ```ruby
 class ResponseHandler
-    def initialize(http_client_handler, start_url, type)
-      @http_client = http_client_handler
-      @start_url = start_url
-      @type = type
-    end
+  def initialize(http_client_handler, start_url, type)
+    @http_client = http_client_handler
+    @start_url = start_url
+    @type = type
+  end
 end
 ```
 
@@ -239,13 +240,13 @@ of pages and also start the page counter.
 
 ```ruby
 def get_first_page
-  #Build the URL -- this could be to add pagination params to the route, or add
-  #  whatever else is necessary to the route
+  # Build the URL -- this could be to add pagination params to the route, or
+  # add whatever else is necessary to the route.
   http_response = @http_client.get("a URL")
 
-  #Generally the first page will contain information about how many pages a paginated
-  #  response will have. Set that here. `@max_pages`
-  #Be sure to set the current page count as well -- @current_page
+  # Generally the first page will contain information about how many pages a
+  # paginated response will have. Set that here: `@max_pages`
+  # Be sure to set the current page count as well: `@current_page`
   build_response(http_response)
 end
 ```
@@ -258,17 +259,16 @@ return a boolean denoting the presence of more pages.
 
 ```ruby
 def get_next_page
-  #Build the URL -- this could be to add pagination params to the route, or add
-  #  whatever else is necessary to the route
+  # Build the URL -- this could be to add pagination params to the route, or
+  # add whatever else is necessary to the route:
   http_response = @http_client.get("a URL")
 
-  #If the http_response is valid then increment the page counter here
+  # If the http_response is valid then increment the page counter here.
   build_response(http_response)
 end
 
 def more_pages?
-  return false if @current_page > @max_pages
-  return true
+  @current_page < @max_pages
 end
 ```
 
@@ -278,9 +278,9 @@ The builder will call `#put_request` when handling put routes.
 
 ```ruby
 def put_request
-  #Build the URL -- this could be to add pagination params to the route, or add
-  #  whatever else is necessary to the route
-  #Also send the body if thats how the client handler is configured
+  # Build the URL -- this could be to add pagination params to the route, or
+  # add whatever else is necessary to the route.
+  # Also send the body if thats how the client handler is configured.
   http_response = @http_client.put("a URL", {})
   build_response(http_response)
 end
@@ -292,14 +292,28 @@ The builder will call `#post_request` when handling post routes.
 
 ```ruby
 def post_request
-  #Build the URL -- this could be to add pagination params to the route, or add
-  #  whatever else is necessary to the route
-  #Also send the body if thats how the client handler is configured
+  # Build the URL -- this could be to add pagination params to the route, or
+  # add whatever else is necessary to the route.
+  # Also send the body if that's how the client handler is configured.
   http_response = @http_client.post("a URL", {})
   build_response(http_response)
 end
 ```
 
+#### For deletes
+
+The builder will call `#delete_request` when handling delete routes.
+
+```ruby
+def delete_request
+  # Build the URL -- this could be to add pagination params to the route, or
+  # add whatever else is necessary to the route.
+  # Also send the body if that's how the client handler is configured.
+  http_response = @http_client.delete("a URL")
+  build_response(http_response)
+end
+```
+
 #### Handling retry-able requests
 
 If requests defined need to be retry-able, extend the response handler by providing
@@ -308,34 +322,35 @@ the following methods.
 ```ruby
 def retryable?(status_code)
   if @opts[:exponential_backoff]
-    #Define the conditions of whether or not the provided status code is retry-able
+    # Define the conditions of whether or not the provided status code is retry-able
+    true 
   else
-    return false
+    false
   end
 end
 
 def reset_retries
-  #Track the number of retries so the request is not retried indefinitely.
-  #  The builder will reset them when it no longer is retrying by calling this
-  #  method
+  # Track the number of retries so the request is not retried indefinitely.
+  # The builder will reset them when it no longer is retrying by calling this
+  # method.
   @retries = 0
 end
 
 def retry_request
-  #Increment the retries here so the request is not retried indefinitely.
+  # Increment the retries here so the request is not retried indefinitely.
   @retries += 1
 
-  #Build the URL -- this could be to add pagination params to the route, or add
-  #  whatever else is necessary to the route
+  # Build the URL -- this could be to add pagination params to the route, or
+  # add whatever else is necessary to the route.
   response = @http_client.the_action_to_retry("a URL")
   build_response(response)
 end
 ```
 
-#### Managing the http response
+#### Managing the HTTP response
 
 The builder defines a default `Response` object that will provide the minimally
-required interface for managing an http response.
+required interface for managing an HTTP response.
 
 ```ruby
 def build_response(http_response)
@@ -373,10 +388,10 @@ is not a "success."
 single_request = client.get_some_object(id: 123)
 
 single_request.on_error do |page, handler|
-  #The page will have all of the status information
-  #The handler is the defined response_handler
-  #Use either to glean more information about why the request was an error and
-  # handle the error here
+  # The page will have all of the status information.
+  # The handler is the defined response_handler.
+  # Use either to glean more information about why the request was an error and
+  # handle the error here.
 end
 
 response_body = single_request.response

data/api_client_builder.gemspec

@@ -1,23 +1,25 @@
-# -*- encoding: utf-8 -*-
-require File.expand_path('../lib/api_client_builder/version', __FILE__)
+require File.expand_path('lib/api_client_builder/version', __dir__)
 
 Gem::Specification.new do |gem|
-  gem.name          = "api_client_builder"
-  gem.summary       = "API Client Builder provides an easy to use interface for creating HTTP api clients"
-  gem.description   = "API Client Builder provides an easy to use interface for creating HTTP api clients"
+  gem.name          = 'api_client_builder'
+  gem.summary       = 'API Client Builder provides an easy to use interface for creating HTTP api clients'
+  gem.description   = 'API Client Builder provides an easy to use interface for creating HTTP api clients'
   gem.authors       = ['Jayce Higgins']
   gem.email         = ['jhiggins@instructure.com', 'eng@instructure.com']
+  gem.homepage      = 'https://github.com/instructure/api-client-builder'
 
-  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'
+  gem.required_ruby_version = '>= 2.3'
 
-  gem.license       = 'MIT'
+  gem.license = 'MIT'
 
   gem.add_development_dependency 'pry'
-  gem.add_development_dependency 'rspec'
-  gem.add_development_dependency 'wwtd'
+  gem.add_development_dependency 'rspec', '~> 3.7'
+  gem.add_development_dependency 'rubocop', '~> 0.57.2'
+  gem.add_development_dependency 'simplecov', '~> 0'
+
+  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,16 @@
+#!/usr/bin/env bash
+
+set -e
+
+docker pull ruby:2.5
+docker pull ruby:2.6
+
+docker run --rm -v "`pwd`:/app" -w /app --user `id -u`:`id -g` -e HOME="/tmp" "ruby:2.3" \
+  /bin/sh -c "echo \"gem: --no-document\" >> ~/.gemrc && bundle install --jobs 5 --quiet && bundle exec rubocop --cache false --fail-level autocorrect"
+
+for version in '2.5' '2.6'; do
+  echo "Testing Ruby $version..."
+  docker run --rm -v "`pwd`:/app" -w /app --user `id -u`:`id -g` \
+    -e HOME="/tmp" "ruby:$version" /bin/sh -c \
+    "echo \"gem: --no-document\" >> ~/.gemrc && bundle install --jobs 5 --quiet && bundle exec rspec"
+done

data/lib/api_client_builder.rb

@@ -0,0 +1,14 @@
+require 'uri'
+
+require_relative 'api_client_builder/version'
+require_relative 'api_client_builder/request'
+require_relative 'api_client_builder/response'
+
+require_relative 'api_client_builder/get_collection_request'
+require_relative 'api_client_builder/get_item_request'
+require_relative 'api_client_builder/post_request'
+require_relative 'api_client_builder/put_request'
+require_relative 'api_client_builder/delete_request'
+require_relative 'api_client_builder/url_generator'
+
+require_relative 'api_client_builder/api_client'