my_api_client 0.14.0 → 0.18.0

data/bin/console

@@ -3,6 +3,10 @@
 
 require 'bundler/setup'
 require 'my_api_client'
+require './example/api_clients/my_error_api_client'
+require './example/api_clients/my_rest_api_client'
+require './example/api_clients/my_pagination_api_client'
+require './example/api_clients/my_status_api_client'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/example/api_clients/application_api_client.rb

@@ -8,14 +8,6 @@ class ApplicationApiClient < MyApiClient::Base
 
   self.logger = ::Logger.new(nil)
 
-  http_open_timeout 2.seconds
-  http_read_timeout 3.seconds
-
-  retry_on MyApiClient::NetworkError, wait: 0.seconds, attempts: 3
-
-  error_handling status_code: 400..499, raise: MyApiClient::ClientError
-  error_handling status_code: 500..599 do |params, logger|
-    logger.warn 'Server error occurred.'
-    raise MyApiClient::ServerError, params
-  end
+  http_open_timeout 5.seconds
+  http_read_timeout 5.seconds
 end

data/example/api_clients/my_pagination_api_client.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'application_api_client'
+
+# An usage example of the `my_api_client`.
+# See also: my_api/app/controllers/pagination_controller.rb
+class MyPaginationApiClient < ApplicationApiClient
+  # GET pagination?page=1
+  def pagination
+    pget 'pagination', paging: '$.links.next', headers: headers, query: { page: 1 }
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end

data/example/api_clients/my_rest_api_client.rb

@@ -18,13 +18,19 @@ class MyRestApiClient < ApplicationApiClient
   end
 
   # POST rest
-  def create_post(title:)
+  def post_post(title:)
     body = { title: title }
     post 'rest', body: body, headers: headers
   end
 
-  # POST/PUT/PATCH rest/:id
-  def update_post(id:, title:)
+  # PUT rest/:id
+  def put_post(id:, title:)
+    body = { title: title }
+    put "rest/#{id}", body: body, headers: headers
+  end
+
+  # PATCH rest/:id
+  def patch_post(id:, title:)
     body = { title: title }
     patch "rest/#{id}", body: body, headers: headers
   end

data/lib/generators/rails/USAGE

@@ -2,7 +2,7 @@ Description:
     Generate a new api client class files.
 
 Example:
-    `rails g api_client path/to/resource get:path/to/resource`
+    `rails g api_client path/to/resource get:path/to/resource` --endpoint https://example.com
 
     This will create:
         create  app/api_clients/application_api_client.rb

data/lib/generators/rails/api_client_generator.rb

@@ -15,6 +15,12 @@ module Rails
              default: %w[get:path/to/resource post:path/to/resource],
              banner: '{method}:{path} {method}:{path}'
 
+    class_option :endpoint,
+                 type: :string,
+                 default: 'https://example.com',
+                 banner: 'https://example.com',
+                 desc: 'Common part of the target API endpoint'
+
     def generate_root_class
       file_path = File.join('app/api_clients', 'application_api_client.rb')
       return if File.exist?(file_path)

data/lib/generators/rails/templates/api_client.rb.erb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class <%= "#{class_name}ApiClient" %> < ::ApplicationApiClient
-  endpoint 'https://example.com'
+  endpoint '<%= options[:endpoint] %>'
 
   # error_handling json: { '$.errors.code': 10 } do |params, logger|
   #   # Behavior when detected an error.

data/lib/generators/rails/templates/application_api_client.rb.erb

@@ -20,15 +20,4 @@ class ApplicationApiClient < MyApiClient::Base
   # seconds.
   #
   # http_read_timeout 3.seconds
-
-  # Catch the exception and re-execution after any seconds, like as ActiveJob.
-  # Please note that it is executed as a synchronous process unlike ActiveJob.
-  #
-  # retry_on MyApiClient::NetworkError, wait: 5.seconds, attempts: 3
-
-  # Set a HTTP response verifyment and behavior. If conflicting conditions are
-  # set, the processing defined later takes precedence
-  #
-  # error_handling status_code: 400..499, raise: MyApiClient::ClientError
-  # error_handling status_code: 500..599, raise: MyApiClient::ServerError
 end

data/lib/generators/rspec/USAGE

@@ -2,7 +2,7 @@ Description:
     Generate a new api client spec files.
 
 Example:
-    rails g rspec:api_client path/to/resource get:path/to/resource`
+    rails g rspec:api_client path/to/resource get:path/to/resource` --endpoint https://example.com
 
     This will create:
         create  spec/api_clients/path/to/resource_api_client_spec.rb

data/lib/generators/rspec/api_client_generator.rb

@@ -16,6 +16,12 @@ module Rspec
                default: %w[get:path/to/resource post:path/to/resource],
                banner: '{method}:{path} {method}:{path}'
 
+      class_option :endpoint,
+                   type: :string,
+                   default: 'https://example.com',
+                   banner: 'https://example.com',
+                   desc: 'Common part of the target API endpoint'
+
       class_option :api_client_specs, type: :boolean, default: true
 
       def generate_api_client_spec

data/lib/generators/rspec/templates/api_client_spec.rb.erb

@@ -11,16 +11,28 @@ RSpec.describe <%= "#{class_name}ApiClient" %>, <%= type_metatag(:api_client) %>
   end
 
   shared_examples 'to handle errors' do
-    it do
-      expect { api_request }
-        .to be_handled_as_an_error(MyApiClient::ClientError)
-        .when_receive(status_code: 400)
+    context 'when the API returns 200 OK' do
+      it do
+        expect { api_request }
+          .not_to be_handled_as_an_error
+          .when_receive(status_code: 200)
+      end
     end
 
-    it do
-      expect { api_request }
-        .to be_handled_as_an_error(MyApiClient::ServerError)
-        .when_receive(status_code: 500)
+    context 'when the API returns 400 Bad Request' do
+      it do
+        expect { api_request }
+          .to be_handled_as_an_error(MyApiClient::ClientError::BadRequest)
+          .when_receive(status_code: 400)
+      end
+    end
+
+    context 'when the API returns 500 Internal Server Error' do
+      it do
+        expect { api_request }
+          .to be_handled_as_an_error(MyApiClient::ServerError::InternalServerError)
+          .when_receive(status_code: 500)
+      end
     end
   end
 <% yeild_request_arguments do |action, http_method, pathname| -%>
@@ -28,22 +40,17 @@ RSpec.describe <%= "#{class_name}ApiClient" %>, <%= type_metatag(:api_client) %>
   describe '#<%= action %>' do
     subject(:api_request) { api_client.<%= action %> }
 
+    it_behaves_like 'to handle errors'
+
     it do
       expect { api_request }
-        .to request_to(:<%= http_method %>, 'https://example.com/<%= pathname %>')
+        .to request_to(:<%= http_method %>, '<%= options[:endpoint] %>/<%= pathname %>')
 <% if http_method == 'get' -%>
         .with(headers: headers, query: {})
 <% else -%>
         .with(headers: headers, body: {})
 <% end -%>
     end
-
-    it_behaves_like 'to handle errors' do
-      it do
-        expect { api_request }.not_to be_handled_as_an_error
-          .when_receive(status_code: 200, body: nil, headers: nil)
-      end
-    end
   end
 <% end -%>
 end

data/lib/my_api_client.rb

@@ -16,7 +16,14 @@ require 'my_api_client/error_handling'
 require 'my_api_client/exceptions'
 require 'my_api_client/request/logger'
 require 'my_api_client/request/executor'
+require 'my_api_client/request/basic'
+require 'my_api_client/request/pagination'
 require 'my_api_client/errors'
+require 'my_api_client/errors/api_limit_error'
+require 'my_api_client/errors/client_error'
+require 'my_api_client/errors/network_error'
+require 'my_api_client/errors/server_error'
+require 'my_api_client/default_error_handlers'
 require 'my_api_client/params/params'
 require 'my_api_client/params/request'
 require 'my_api_client/request'

data/lib/my_api_client/base.rb

@@ -9,15 +9,17 @@ module MyApiClient
     include MyApiClient::Request
 
     if ActiveSupport::VERSION::STRING >= '5.2.0'
-      class_attribute :logger, instance_writer: false, default: ::Logger.new(STDOUT)
+      class_attribute :logger, instance_writer: false, default: ::Logger.new($stdout)
       class_attribute :error_handlers, instance_writer: false, default: []
     else
       class_attribute :logger
       class_attribute :error_handlers
-      self.logger = ::Logger.new(STDOUT)
+      self.logger = ::Logger.new($stdout)
       self.error_handlers = []
     end
 
+    include MyApiClient::DefaultErrorHandlers
+
     # NOTE: This class **MUST NOT** implement #initialize method. Because it
     #       will become constraint that need call #super in the #initialize at
     #       definition of the child classes.

data/lib/my_api_client/default_error_handlers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Provides default error handlers.
+  module DefaultErrorHandlers
+    extend ActiveSupport::Concern
+
+    # rubocop:disable Metrics/BlockLength
+    included do
+      # NOTE: The built-in error handlers are following. Although they are prepared
+      #       to save the trouble of defining, but you can override any error handlers
+      #       in your API client class.
+      error_handling status_code: 400..499, raise: ClientError
+      error_handling status_code: 400, raise: ClientError::BadRequest
+      error_handling status_code: 401, raise: ClientError::Unauthorized
+      error_handling status_code: 402, raise: ClientError::PaymentRequired
+      error_handling status_code: 403, raise: ClientError::Forbidden
+      error_handling status_code: 404, raise: ClientError::NotFound
+      error_handling status_code: 405, raise: ClientError::MethodNotAllowed
+      error_handling status_code: 406, raise: ClientError::NotAcceptable
+      error_handling status_code: 407, raise: ClientError::ProxyAuthenticationRequired
+      error_handling status_code: 408, raise: ClientError::RequestTimeout
+      error_handling status_code: 409, raise: ClientError::Conflict
+      error_handling status_code: 410, raise: ClientError::Gone
+      error_handling status_code: 411, raise: ClientError::LengthRequired
+      error_handling status_code: 412, raise: ClientError::PreconditionFailed
+      error_handling status_code: 413, raise: ClientError::RequestEntityTooLarge
+      error_handling status_code: 414, raise: ClientError::RequestUriTooLong
+      error_handling status_code: 415, raise: ClientError::UnsupportedMediaType
+      error_handling status_code: 416, raise: ClientError::RequestedRangeNotSatisfiable
+      error_handling status_code: 417, raise: ClientError::ExpectationFailed
+      error_handling status_code: 418, raise: ClientError::IamTeapot
+      error_handling status_code: 421, raise: ClientError::MisdirectedRequest
+      error_handling status_code: 422, raise: ClientError::UnprocessableEntity
+      error_handling status_code: 423, raise: ClientError::Locked
+      error_handling status_code: 424, raise: ClientError::FailedDependency
+      error_handling status_code: 425, raise: ClientError::TooEarly
+      error_handling status_code: 426, raise: ClientError::UpgradeRequired
+      error_handling status_code: 428, raise: ClientError::PreconditionRequired
+      error_handling status_code: 429, raise: ClientError::TooManyRequests
+      error_handling status_code: 431, raise: ClientError::RequestHeaderFieldsTooLarge
+      error_handling status_code: 451, raise: ClientError::UnavailableForLegalReasons
+
+      error_handling status_code: 500..599, raise: ServerError
+      error_handling status_code: 500, raise: ServerError::InternalServerError
+      error_handling status_code: 501, raise: ServerError::NotImplemented
+      error_handling status_code: 502, raise: ServerError::BadGateway
+      error_handling status_code: 503, raise: ServerError::ServiceUnavailable
+      error_handling status_code: 504, raise: ServerError::GatewayTimeout
+      error_handling status_code: 505, raise: ServerError::HttpVersionNotSupported
+      error_handling status_code: 506, raise: ServerError::VariantAlsoNegotiates
+      error_handling status_code: 507, raise: ServerError::InsufficientStorage
+      error_handling status_code: 508, raise: ServerError::LoopDetected
+      error_handling status_code: 509, raise: ServerError::BandwidthLimitExceeded
+      error_handling status_code: 510, raise: ServerError::NotExtended
+      error_handling status_code: 511, raise: ServerError::NetworkAuthenticationRequired
+
+      # Catch the exception and re-execution after any seconds, like as ActiveJob.
+      # Please note that it is executed as a synchronous process unlike ActiveJob.
+      retry_on NetworkError, wait: 0.3.seconds, attempts: 3
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end

data/lib/my_api_client/error_handling.rb

@@ -9,9 +9,8 @@ module MyApiClient
   # @example
   #   error_handling status_code: 200, json: :forbid_nil
   #   error_handling status_code: 400..499, raise: MyApiClient::ClientError
-  #   error_handling status_code: 500..599 do |params, logger|
+  #   error_handling status_code: 500..599, raise: MyApiClient::ServerError do |params, logger|
   #     logger.warn 'Server error occurred.'
-  #     raise MyApiClient::ServerError, params
   #   end
   #
   #   error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
@@ -29,10 +28,11 @@ module MyApiClient
       # @option status_code [String, Range, Integer, Regexp]
       #   Verifies response HTTP status code and raises error if matched
       # @option json [Hash, Symbol]
-      #   Verifies response body as JSON and raises error if matched.
-      #   If specified `:forbid_nil`, it forbid `nil` on response_body.
+      #   Specify the validation target value path included in the response body
+      #   as JsonPath expression.
+      #   If specified `:forbid_nil`, it forbid `nil` at the response body.
       # @option with [Symbol]
-      #   Calls specified method when error detected
+      #   Calls specified method before raising exception when error detected.
       # @option raise [MyApiClient::Error]
       #   Raises specified error when an invalid response detected.
       #   Should be inherited `MyApiClient::Error` class.
@@ -41,7 +41,7 @@ module MyApiClient
       #   If the error detected, retries the API request. Requires `raise` option.
       #   You can set `true` or `retry_on` options (`wait` and `attempts`).
       # @yield [MyApiClient::Params::Params, MyApiClient::Request::Logger]
-      #   Executes the block when error detected.
+      #   Executes the block before raising exception when error detected.
       #   Forbid to be used with the` retry` option.
       def error_handling(**options, &block)
         options[:block] = block

data/lib/my_api_client/error_handling/generator.rb

@@ -23,8 +23,8 @@ module MyApiClient
       #   Raises specified error when error detected. default: MyApiClient::Error
       # @option block [Proc]
       #   Executes the block when error detected
-      # @return [Proc]
-      #   Returns value as `Proc`.
+      # @return [Proc, nil]
+      #   Returns the error handler as "Proc". If no error occurs, return `nil`.
       def initialize(**options)
         options[:raise] ||= MyApiClient::Error
         verify_and_set_arguments(**options)
@@ -43,14 +43,32 @@ module MyApiClient
 
       def generate_error_handler
         if _block
-          ->(params, logger) { _block.call(params, logger) }
+          block_caller
         elsif _with
-          ->(params, logger) { _instance.send(_with, params, logger) }
+          method_caller
         else
-          ->(params, _) { raise _raise, params }
+          error_raiser
         end
       end
 
+      def block_caller
+        lambda { |params, logger|
+          _block.call(params, logger)
+          error_raiser.call(params, logger)
+        }
+      end
+
+      def method_caller
+        lambda { |params, logger|
+          _instance.send(_with, params, logger)
+          error_raiser.call(params, logger)
+        }
+      end
+
+      def error_raiser
+        ->(params, _) { raise _raise, params }
+      end
+
       # Verify given options and raise error if they are incorrect.
       # If not, set them to instance variables.
       #
@@ -67,7 +85,6 @@ module MyApiClient
         end
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity
       def match?(operator, target)
         case operator
         when nil
@@ -84,7 +101,6 @@ module MyApiClient
           raise "Unexpected operator type was given: #{operator.inspect}"
         end
       end
-      # rubocop:enable Metrics/CyclomaticComplexity
 
       def match_all?(json, response_body)
         return true if json.nil?

data/lib/my_api_client/errors.rb

@@ -4,6 +4,7 @@ module MyApiClient
   # The ancestor class for all API request error
   class Error < StandardError
     attr_reader :params
+
     delegate :metadata, to: :params
     alias to_bugsnag metadata
 
@@ -25,57 +26,4 @@ module MyApiClient
       { error: super, params: params }.inspect
     end
   end
-
-  NETWORK_ERRORS = [
-    Faraday::TimeoutError,
-    Faraday::ConnectionFailed,
-    Faraday::SSLError,
-    OpenSSL::SSL::SSLError,
-    Net::OpenTimeout,
-    Net::ReadTimeout,
-    SocketError,
-  ].freeze
-
-  # Raises it when occurred to some network error
-  class NetworkError < Error
-    attr_reader :original_error
-
-    # Initialize the error class
-    #
-    # @param params [MyApiClient::Params::Params]
-    #   The request and response parameters
-    # @param original_error [StandardError]
-    #   Some network error
-    def initialize(params, original_error)
-      @original_error = original_error
-      super params, original_error.message
-    end
-
-    # Returns contents as string for to be readable for human
-    #
-    # @return [String] Contents as string
-    def inspect
-      { error: original_error, params: params }.inspect
-    end
-
-    # Generate metadata for bugsnag.
-    #
-    # @return [Hash] Metadata for bugsnag
-    def metadata
-      super.merge(original_error: original_error.inspect)
-    end
-  end
-
-  # NOTE: The built-in error classes are following. Although they are prepared
-  #       to save the trouble of defining, but you can create any error classes
-  #       which inherit the ancestor error class.
-
-  # For 4xx client error
-  class ClientError < Error; end
-
-  # For 5xx server error
-  class ServerError < Error; end
-
-  # For API request limit error
-  class ApiLimitError < Error; end
 end