my_api_client 0.14.0.pre → 0.17.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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'my_errors'
+
+# An usage example of the `my_api_client`.
+class ApplicationApiClient < MyApiClient::Base
+  endpoint ENV['MY_API_ENDPOINT']
+
+  self.logger = ::Logger.new(nil)
+
+  http_open_timeout 5.seconds
+  http_read_timeout 5.seconds
+end

data/example/api_clients/my_error_api_client.rb

@@ -0,0 +1,34 @@
+# 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 MyErrorApiClient < ApplicationApiClient
+  error_handling json: { '$.error.message': /You requested error code/ },
+                 raise: MyErrors::ErrorCodeOther
+
+  error_handling json: { '$.error.code': :zero? },
+                 raise: MyErrors::ErrorCode00
+
+  error_handling json: { '$.error.code': 10 },
+                 raise: MyErrors::ErrorCode10
+
+  error_handling json: { '$.error.code': 20..29 },
+                 raise: MyErrors::ErrorCode2x
+
+  error_handling json: { '$.error.code': 30 },
+                 status_code: 400,
+                 raise: MyErrors::ErrorCode30
+
+  # GET error/:code
+  def get_error(code:)
+    get "error/#{code}", headers: headers
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end

data/example/api_clients/my_errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MyErrors
+  # 400 Bad Request
+  class BadRequest < MyApiClient::ClientError; end
+
+  # 401 Unauthorized
+  class Unauthorized < MyApiClient::ClientError; end
+
+  # 403 Forbidden
+  class Forbidden < MyApiClient::ClientError; end
+
+  # Error code: 0
+  class ErrorCode00 < MyApiClient::ClientError; end
+
+  # Error code: 10
+  class ErrorCode10 < MyApiClient::ClientError; end
+
+  # Error code: 20 to 29
+  class ErrorCode2x < MyApiClient::ClientError; end
+
+  # Error code: 30
+  class ErrorCode30 < MyApiClient::ClientError; end
+
+  # Error code: other
+  class ErrorCodeOther < MyApiClient::ClientError; end
+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

@@ -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/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,6 +40,8 @@ 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 %>')
@@ -37,13 +51,6 @@ RSpec.describe <%= "#{class_name}ApiClient" %>, <%= type_metatag(:api_client) %>
         .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?