my_api_client 0.13.0 → 0.16.1

data/example/api_clients/my_rest_api_client.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'application_api_client'
+
+# An usage example of the `my_api_client`.
+# See also: my_api/app/controllers/rest_controller.rb
+class MyRestApiClient < ApplicationApiClient
+  # GET rest
+  def get_posts(order: :asc)
+    order = :desc unless order == :asc
+    query = { order: order }
+    get 'rest', query: query, headers: headers
+  end
+
+  # GET rest/:id
+  def get_post(id:)
+    get "rest/#{id}", headers: headers
+  end
+
+  # POST rest
+  def post_post(title:)
+    body = { title: title }
+    post 'rest', body: body, headers: headers
+  end
+
+  # 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
+
+  # DELETE rest/:id
+  def delete_post(id:)
+    delete "rest/#{id}", headers: headers
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end

data/example/api_clients/my_status_api_client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'application_api_client'
+
+# An usage example of the `my_api_client`.
+# See also: my_api/app/controllers/status_controller.rb
+class MyStatusApiClient < ApplicationApiClient
+  error_handling status_code: 400, raise: MyErrors::BadRequest
+  error_handling status_code: 401, raise: MyErrors::Unauthorized
+  error_handling status_code: 403, raise: MyErrors::Forbidden
+
+  # GET status/:status
+  def get_status(status:)
+    get "status/#{status}", headers: headers
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end

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/my_api_client.rb

@@ -11,11 +11,19 @@ require 'my_api_client/service_abstract'
 require 'my_api_client/version'
 require 'my_api_client/config'
 require 'my_api_client/error_handling/generator'
-require 'my_api_client/error_handling/process_retry_option'
+require 'my_api_client/error_handling/retry_option_processor'
 require 'my_api_client/error_handling'
 require 'my_api_client/exceptions'
-require 'my_api_client/logger'
+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

@@ -18,26 +18,10 @@ module MyApiClient
       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.
-
-    HTTP_METHODS = %i[get post patch delete].freeze
-
-    HTTP_METHODS.each do |http_method|
-      class_eval <<~METHOD, __FILE__, __LINE__ + 1
-        # Description of ##{http_method}
-        #
-        # @param pathname [String]
-        # @param headers [Hash, nil]
-        # @param query [Hash, nil]
-        # @param body [Hash, nil]
-        # @return [Sawyer::Resouce] description_of_returned_object
-        def #{http_method}(pathname, headers: nil, query: nil, body: nil)
-          _request :#{http_method}, pathname, headers, query, body, logger
-        end
-      METHOD
-    end
-    alias put patch
   end
 end

data/lib/my_api_client/config.rb

@@ -16,34 +16,5 @@ module MyApiClient
         METHOD
       end
     end
-
-    # Extracts schema and hostname from endpoint
-    #
-    # @example Extracts schema and hostname from 'https://example.com/path/to/api'
-    #   schema_and_hostname # => 'https://example.com'
-    # @return [String] description_of_returned_object
-    def schema_and_hostname
-      if _uri.default_port == _uri.port
-        "#{_uri.scheme}://#{_uri.host}"
-      else
-        "#{_uri.scheme}://#{_uri.host}:#{_uri.port}"
-      end
-    end
-
-    # Extracts pathname from endpoint
-    #
-    # @example Extracts pathname from 'https://example.com/path/to/api'
-    #   common_path # => 'path/to/api'
-    # @return [String] The pathanem
-    def common_path
-      _uri.path
-    end
-
-    private
-
-    # @return [URI] Returns a memoized URI instance
-    def _uri
-      @_uri ||= URI.parse(endpoint)
-    end
   end
 end

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.
@@ -40,30 +40,20 @@ module MyApiClient
       # @option retry [TrueClass, Hash]
       #   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::Logger]
-      #   Executes the block when error detected.
+      # @yield [MyApiClient::Params::Params, MyApiClient::Request::Logger]
+      #   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
-        retry_options = ProcessRetryOption.call(error_handling_options: options)
+        retry_options = RetryOptionProcessor.call(error_handling_options: options)
         retry_on(options[:raise], **retry_options) if retry_options
 
-        temp = error_handlers.dup
-        temp << ->(response) { Generator.call(**options.merge(response: response)) }
-        self.error_handlers = temp
+        new_error_handlers = error_handlers.dup
+        new_error_handlers << lambda { |instance, response|
+          Generator.call(**options.merge(instance: instance, response: response))
+        }
+        self.error_handlers = new_error_handlers
       end
     end
-
-    # The error handlers defined later takes precedence
-    #
-    # @param response [Sawyer::Response] describe_params_here
-    # @return [Proc, Symbol, nil] description_of_returned_object
-    def error_handling(response)
-      error_handlers.reverse_each do |error_handler|
-        result = error_handler.call(response)
-        return result unless result.nil?
-      end
-      nil
-    end
   end
 end

data/lib/my_api_client/error_handling/generator.rb

@@ -4,10 +4,12 @@ module MyApiClient
   module ErrorHandling
     # Generates an error handler proc (or symbol)
     class Generator < ServiceAbstract
-      ARGUMENTS = %i[response status_code json with raise block].freeze
+      ARGUMENTS = %i[instance response status_code json with raise block].freeze
 
       # @param options [Hash]
       #   Options for this generator
+      # @option instance [MyApiClient::Base]
+      #   The API client class.
       # @option response [Sawyer::Response]
       #   The target of verifying
       # @option status_code [String, Range, Integer, Regexp]
@@ -21,10 +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` if given `raise` or `block` option
-      # @return [Symbol]
-      #   Returns value as `Symbol` if given `with` option
+      # @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)
@@ -38,15 +38,37 @@ module MyApiClient
         return unless match?(_status_code, _response.status)
         return unless match_all?(_json, _response.body)
 
+        generate_error_handler
+      end
+
+      def generate_error_handler
         if _block
-          ->(params, logger) { _block.call(params, logger) }
+          block_caller
         elsif _with
-          _with
+          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.
       #
@@ -63,7 +85,6 @@ module MyApiClient
         end
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity
       def match?(operator, target)
         case operator
         when nil
@@ -80,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/error_handling/{process_retry_option.rb → retry_option_processor.rb}

@@ -3,7 +3,7 @@
 module MyApiClient
   module ErrorHandling
     # Processes the `retry` option.
-    class ProcessRetryOption < ServiceAbstract
+    class RetryOptionProcessor < ServiceAbstract
       # @param error_handling_options [Hash]
       #   Options for the retry.
       # @option raise [MyApiClient::Error]

data/lib/my_api_client/errors.rb

@@ -25,57 +25,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