active_call-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d89661cdfe0817001170ea4c3bbcefdde885817d1083135fb2579508b0495cc
+  data.tar.gz: 0f5e046770d937b922e26fe222682889eef76e4493cad13b13b846e0edf5541a
+SHA512:
+  metadata.gz: 23546750b36d58b739fa1e02cb1978df326bf7453c40ddf843b28ce17c66737b6a5d5cbd10b2fb25d8605ae0e47ff4479672497529ba74f9fcac8cc56015b5a0
+  data.tar.gz: 5f9459ff18547e0bcb1dc8bf2373ef628aa3e30451e7310a04c4f84a3e28095872bab603ce3b6a136d73a1b78a82a3b7d03a96f4a16ea7d2a17cfda4bf669b34

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,73 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - active_call-api.gemspec
+    - bin/*
+    - 'vendor/**/*'
+    - 'gem/**/*'
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Layout/LineLength:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/*/**.rb
+    - lib/active_call/api.rb
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  EnforcedStyleForLeadingUnderscores: required
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+# Disabled for now. Can't get it to work with the commented rules.
+Style/ClassAndModuleChildren:
+  Enabled: false
+  # EnforcedStyle: compact
+  # EnforcedStyleForClasses: compact
+  # EnforcedStyleForModules: nested
+  # Exclude:
+  #   - lib/active_call/api.rb
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/SymbolArray:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-25
+
+- Initial release.
+- Initial `ActiveCall::*Error` classes with overridable `exception_mapping` and `connection` methods.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kobus Joubert
+
+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

@@ -0,0 +1,293 @@
+# Active Call - Api
+
+Active Call - API is an extension of [Active Call](https://rubygems.org/gems/active_call) that provides a standardized way to create service objects for REST API endpoints.
+
+Before proceeding, please review the [Active Call Usage](https://github.com/kobusjoubert/active_call?tab=readme-ov-file#usage) section. It takes just 55 seconds.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+Set up an `ActiveCall::Base` base service class for the REST API and include `ActiveCall::Api`.
+
+```ruby
+require 'active_call'
+require 'active_call/api'
+
+class YourGem::BaseService < ActiveCall::Base
+  include ActiveCall::Api
+
+  self.abstract_class = true
+
+  ...
+```
+
+Implement a `connection` method to hold a [Faraday::Connection](https://lostisland.github.io/faraday/#/getting-started/quick-start?id=faraday-connection) object.
+
+This connection instance will then be used in the `call` methods of the individual service objects.
+
+```ruby
+class YourGem::BaseService < ActiveCall::Base
+  ...
+
+  config_accessor :api_key, default: ENV['API_KEY'], instance_writer: false
+  config_accessor :logger, default: Logger.new($stdout), instance_writer: false
+
+  def connection
+    @_connection ||= Faraday.new do |conn|
+      conn.url_prefix = 'https://example.com/api/v1'
+      conn.request :authorization, 'X-API-Key', api_key
+      conn.request :json
+      conn.response :json
+      conn.response :logger, logger, formatter: Faraday::Logging::ColorFormatter, prefix: { request: 'YourGem', response: 'YourGem' } do |logger|
+        logger.filter(/(Authorization:).*"(.+)."/i, '\1 [FILTERED]')
+      end
+      conn.adapter Faraday.default_adapter
+    end
+  end
+
+  ...
+```
+
+You can now create a REST API service object like so.
+
+```ruby
+class YourGem::SomeResource::UpdateService < YourGem::BaseService
+  attr_reader :id, :first_name, :last_name
+
+  validates :id, :first_name, :last_name, presence: true
+
+  def initialize(id:, first_name:, last_name:)
+    @id         = id
+    @first_name = first_name
+    @last_name  = last_name
+  end
+
+  # PUT /api/v1/someresource/:id
+  def call
+    connection.put("someresource/#{id}", first_name: first_name, last_name: last_name)
+  end
+end
+```
+
+### Using `call`
+
+```ruby
+service = YourGem::SomeResource::UpdateService.call(id: '1', first_name: 'Stan', last_name: 'Marsh')
+service.success? # => true
+service.errors # => #<ActiveModel::Errors []>
+service.response # => #<Faraday::Response ...>
+service.response.status # => 200
+service.response.body # => {}
+```
+
+### Using `call!`
+
+```ruby
+begin
+  service = YourGem::SomeResource::UpdateService.call!(id: '1', first_name: 'Stan', last_name: '')
+rescue ActiveCall::ValidationError => exception
+  exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=last_name, type=blank, options={}>]>
+  exception.errors.full_messages # => ["Last name can't be blank"]
+rescue ActiveCall::UnprocessableEntityError => exception
+  exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=unprocessable_entity, options={}>]>
+  exception.errors.full_messages # => ["Unprocessable Entity"]
+  exception.response # => #<Faraday::Response ...>
+  exception.response.status # => 422
+  exception.response.body # => {}
+end
+```
+
+## Errors
+
+The following exceptions will get raised when using `call!` and the request was unsuccessful.
+
+| HTTP Status Code | Exception Class                                |
+| :--------------: | ---------------------------------------------- |
+|  **4xx**         | `ActiveCall::ClientError`                      |
+|  **400**         | `ActiveCall::BadRequestError`                  |
+|  **401**         | `ActiveCall::UnauthorizedError`                |
+|  **403**         | `ActiveCall::ForbiddenError`                   |
+|  **404**         | `ActiveCall::NotFoundError`                    |
+|  **406**         | `ActiveCall::NotAcceptableError`               |
+|  **407**         | `ActiveCall::ProxyAuthenticationRequiredError` |
+|  **408**         | `ActiveCall::RequestTimeoutError`              |
+|  **409**         | `ActiveCall::ConflictError`                    |
+|  **422**         | `ActiveCall::UnprocessableEntityError`         |
+|  **429**         | `ActiveCall::TooManyRequestsError`             |
+|  **5xx**         | `ActiveCall::ServerError`                      |
+|  **500**         | `ActiveCall::InternalServerError`              |
+|  **501**         | `ActiveCall::NotImplementedError`              |
+|  **502**         | `ActiveCall::BadGatewayError`                  |
+|  **503**         | `ActiveCall::ServiceUnavailableError`          |
+|  **504**         | `ActiveCall::GatewayTimeoutError`              |
+
+**400..499** errors are subclasses of `ActiveCall::ClientError`.
+
+**500..599** errors are subclasses of `ActiveCall::ServerError`.
+
+For any explicit HTTP status code not listed here, an `ActiveCall::ClientError` exception gets raised for **4xx** HTTP status codes and an `ActiveCall::ServerError` exception for **5xx** HTTP status codes.
+
+### Custom Exception Classes
+
+If you want to use your error classes instead, override the `exception_mapping` class method.
+
+```ruby
+class YourGem::BaseService < ActiveCall::Base
+  ...
+
+  class << self
+    def exception_mapping
+      {
+        validation_error:              YourGem::ValidationError,
+        request_error:                 YourGem::RequestError,
+        client_error:                  YourGem::ClientError,
+        server_error:                  YourGem::ServerError,
+        bad_request:                   YourGem::BadRequestError,
+        unauthorized:                  YourGem::UnauthorizedError,
+        forbidden:                     YourGem::ForbiddenError,
+        not_found:                     YourGem::NotFoundError,
+        not_acceptable:                YourGem::NotAcceptableError,
+        proxy_authentication_required: YourGem::ProxyAuthenticationRequiredError,
+        request_timeout:               YourGem::RequestTimeoutError,
+        conflict:                      YourGem::ConflictError,
+        unprocessable_entity:          YourGem::UnprocessableEntityError,
+        too_many_requests:             YourGem::TooManyRequestsError,
+        internal_server_error:         YourGem::InternalServerError,
+        bad_gateway:                   YourGem::BadGatewayError,
+        service_unavailable:           YourGem::ServiceUnavailableError,
+        gateway_timeout:               YourGem::GatewayTimeoutError
+      }
+    end
+  end
+
+  ...
+```
+
+### Error Types
+
+The methods below determine what **type** of error gets added to the **errors** object.
+
+```ruby
+service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=bad_request, options={}>]>
+```
+
+When using `.call!`, they map to the `exception_mapping` above, so `bad_request?` maps to `bad_request`.
+
+```ruby
+exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=bad_request, options={}>]>
+```
+
+```ruby
+class YourGem::BaseService < ActiveCall::Base
+  ...
+
+  def bad_request?
+    response.status == 400
+  end
+
+  def unauthorized?
+    response.status == 401
+  end
+
+  def forbidden?
+    response.status == 403
+  end
+
+  def not_found?
+    response.status == 404
+  end
+
+  def not_acceptable?
+    response.status == 406
+  end
+
+  def proxy_authentication_required?
+    response.status == 407
+  end
+
+  def request_timeout?
+    response.status == 408
+  end
+
+  def conflict?
+    response.status == 409
+  end
+
+  def unprocessable_entity?
+    response.status == 422
+  end
+
+  def too_many_requests?
+    response.status == 429
+  end
+
+  def internal_server_error?
+    response.status == 500
+  end
+
+  def bad_gateway?
+    response.status == 502
+  end
+
+  def service_unavailable?
+    response.status == 503
+  end
+
+  def gateway_timeout?
+    response.status == 504
+  end
+```
+
+These methods can be overridden to add more rules when an API does not respond with the relevant HTTP status code.
+
+A common occurrence is when an API returns an HTTP status code of 400 with an error message in the body for anything related to client errors, sometimes even for a resource that could not be found.
+
+It is not required to override any of these methods since all **4xx** and **5xx** errors add a `client_error` or `server_error` type to the errors object, respectively.
+
+While not required, handling specific errors based on their actual meaning makes for a happier development experience.
+
+You have access to the full `Farady::Response` object set to the `response` attribute, so you can use `response.status` and `response.body` to determine the type of error.
+
+Perhaps the API does not always respond with a **422** HTTP status code for unprocessable entity requests or a **404** HTTP status for resources not found.
+
+```ruby
+class YourGem::BaseService < ActiveCall::Base
+  ...
+
+  def not_found?
+    response.status == 404 || (response.status == 400 && response.body['error_code'] == 'not_found')
+  end
+
+  def unprocessable_entity?
+    response.status == 422 || (response.status == 400 && response.body['error_code'] == 'not_processable')
+  end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kobusjoubert/active_call-api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/active_call/api/locale/en.yml

@@ -0,0 +1,25 @@
+en:
+  activemodel:
+    errors:
+      # The values :model, :attribute and :value are always available for interpolation.
+      # The value :count is available when applicable. Can be used for pluralization.
+      models:
+        active_call/base:
+          bad_gateway: 'Bad Gateway'
+          bad_request: 'Bad Request'
+          client_error: 'Client Error'
+          conflict: 'Conflict'
+          forbidden: 'Forbidden'
+          gateway_timeout: 'Gateway Timeout'
+          internal_server_error: 'Internal Server Error'
+          not_found: 'Not Found'
+          not_acceptable: 'Not Acceptable'
+          not_implemented: 'Not Implemented'
+          proxy_authentication_required: 'Proxy Authentication Required'
+          request_error: 'Request Error'
+          request_timeout: 'Request Timeout'
+          server_error: 'Server Error'
+          service_unavailable: 'Service Unavailable'
+          too_many_requests: 'Too Many Requests'
+          unauthorized: 'Unauthorized'
+          unprocessable_entity: 'Unprocessable Entity'

data/lib/active_call/api/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveCall
+  module Api
+    VERSION = '0.1.0'
+  end
+end

data/lib/active_call/api.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require 'active_call'
+require 'faraday'
+require 'faraday/retry'
+require 'faraday/logging/color_formatter'
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/error.rb")
+loader.collapse("#{__dir__}/api/concerns")
+loader.push_dir(__dir__, namespace: ActiveCall)
+loader.setup
+
+require_relative 'error'
+require_relative 'api/version'
+
+module ActiveCall::Api
+  extend ActiveSupport::Concern
+
+  included do
+    include ActiveModel::Validations
+
+    validate on: :response do
+      throw :abort if response.is_a?(Enumerable)
+
+      # ==== 5xx
+      errors.add(:base, :not_implemented)               and throw :abort if not_implemented?
+      errors.add(:base, :bad_gateway)                   and throw :abort if bad_gateway?
+      errors.add(:base, :service_unavailable)           and throw :abort if service_unavailable?
+      errors.add(:base, :gateway_timeout)               and throw :abort if gateway_timeout?
+      errors.add(:base, :internal_server_error)         and throw :abort if internal_server_error?
+
+      # We'll use `server_error` for every 5xx error that we don't have an explicit exception class for.
+      errors.add(:base, :server_error)                  and throw :abort if response.status >= 500
+
+      # ==== 4xx
+      errors.add(:base, :unauthorized)                  and throw :abort if unauthorized?
+      errors.add(:base, :forbidden)                     and throw :abort if forbidden?
+      errors.add(:base, :not_found)                     and throw :abort if not_found?
+      errors.add(:base, :proxy_authentication_required) and throw :abort if proxy_authentication_required?
+      errors.add(:base, :request_timeout)               and throw :abort if request_timeout?
+      errors.add(:base, :conflict)                      and throw :abort if conflict?
+      errors.add(:base, :unprocessable_entity)          and throw :abort if unprocessable_entity?
+      errors.add(:base, :too_many_requests)             and throw :abort if too_many_requests?
+
+      # Check for bad_request here since some APIs will use status 400 as a general response for all errors.
+      errors.add(:base, :bad_request)                   and throw :abort if bad_request?
+
+      # We'll use `client_error` for every 4xx error that we don't have an explicit exception class for.
+      errors.add(:base, :client_error)                  and throw :abort if response.status >= 400
+    end
+
+    private_class_method :api_validation_error
+    private_class_method :api_request_error
+
+    private
+
+    # Used in Enumerable subclasses when retrieving paginated lists from an API endpoint.
+    delegate :exception_for, to: :class
+  end
+
+  class_methods do
+    # If you want to use your error classes instead, override the `exception_mapping` class method.
+    #
+    # ==== Examples
+    #
+    #   class YourGem::BaseService < ActiveCall::Base
+    #     class << self
+    #       def exception_mapping
+    #         {
+    #           validation_error: YourGem::ValidationError,
+    #           request_error:    YourGem::RequestError,
+    #           client_error:     YourGem::ClientError,
+    #           server_error:     YourGem::ServerError,
+    #           bad_request:      YourGem::BadRequestError,
+    #           unauthorized:     YourGem::UnauthorizedError,
+    #           ...
+    #         }
+    #       end
+    #
+    def exception_mapping
+      {
+        validation_error:              ActiveCall::ValidationError,
+        request_error:                 ActiveCall::RequestError,
+        client_error:                  ActiveCall::ClientError,
+        server_error:                  ActiveCall::ServerError,
+        bad_request:                   ActiveCall::BadRequestError,
+        unauthorized:                  ActiveCall::UnauthorizedError,
+        forbidden:                     ActiveCall::ForbiddenError,
+        not_found:                     ActiveCall::NotFoundError,
+        not_acceptable:                ActiveCall::NotAcceptableError,
+        proxy_authentication_required: ActiveCall::ProxyAuthenticationRequiredError,
+        request_timeout:               ActiveCall::RequestTimeoutError,
+        conflict:                      ActiveCall::ConflictError,
+        unprocessable_entity:          ActiveCall::UnprocessableEntityError,
+        too_many_requests:             ActiveCall::TooManyRequestsError,
+        internal_server_error:         ActiveCall::InternalServerError,
+        not_implemented:               ActiveCall::NotImplementedError,
+        bad_gateway:                   ActiveCall::BadGatewayError,
+        service_unavailable:           ActiveCall::ServiceUnavailableError,
+        gateway_timeout:               ActiveCall::GatewayTimeoutError
+      }.freeze
+    end
+
+    # Using `call`.
+    #
+    # ==== Examples
+    #
+    #   service = YourGem::SomeResource::UpdateService.call(id: '1', first_name: 'Stan', last_name: 'Marsh')
+    #   service.success? # => true
+    #   service.errors # => #<ActiveModel::Errors []>
+    #   service.response # => #<Faraday::Response ...>
+    #   service.response.status # => 200
+    #   service.response.body # => {}
+    #
+    # Using `call!`.
+    #
+    # ==== Examples
+    #
+    #   begin
+    #     service = YourGem::SomeResource::UpdateService.call!(id: '1', first_name: 'Stan', last_name: '')
+    #   rescue ActiveCall::ValidationError => exception
+    #     exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=last_name, type=blank, options={}>]>
+    #     exception.errors.full_messages # => ["Last name can't be blank"]
+    #   rescue ActiveCall::UnprocessableEntityError => exception
+    #     exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=unprocessable_entity, options={}>]>
+    #     exception.errors.full_messages # => ["Unprocessable Entity"]
+    #     exception.response # => #<Faraday::Response ...>
+    #     exception.response.status # => 200
+    #     exception.response.body # => {}
+    #   end
+    #
+    def call!(...)
+      super
+    rescue ActiveCall::ValidationError => e
+      raise api_validation_error(e)
+    rescue ActiveCall::RequestError => e
+      raise api_request_error(e)
+    end
+
+    def exception_for(response, errors, message = nil)
+      exception_type = errors.details[:base].first[:error]
+
+      case exception_type
+      when *exception_mapping.keys
+        exception_mapping[exception_type].new(response, errors, message)
+      else
+        exception_mapping[:request_error].new(response, errors, message)
+      end
+    end
+
+    def api_validation_error(exception)
+      exception_mapping[:validation_error].new(exception.errors, exception.message)
+    end
+
+    def api_request_error(exception)
+      exception_for(exception.response, exception.errors, exception.message)
+    end
+  end
+
+  # Subclasses must implement a `connection` method to hold a `Faraday::Connection` object.
+  #
+  # This connection instance will then be used in the `call` methods of the individual service objects.
+  #
+  # ==== Examples
+  #
+  #   class YourGem::BaseService < ActiveCall::Base
+  #     config_accessor :api_key, default: ENV['API_KEY'], instance_writer: false
+  #     config_accessor :logger, default: Logger.new($stdout), instance_writer: false
+  #
+  #     def connection
+  #       @_connection ||= Faraday.new do |conn|
+  #         conn.url_prefix = 'https://example.com/api/v1'
+  #         conn.request :authorization, 'X-API-Key', api_key
+  #         conn.request :json
+  #         conn.response :json
+  #         conn.response :logger, logger, formatter: Faraday::Logging::ColorFormatter, prefix: { request: 'YourGem', response: 'YourGem' } do |logger|
+  #           logger.filter(/(Authorization:).*"(.+)."/i, '\1 [FILTERED]')
+  #         end
+  #         conn.adapter Faraday.default_adapter
+  #       end
+  #     end
+  #
+  # You can now create a REST API service object like so.
+  #
+  #   class YourGem::SomeResource::UpdateService < YourGem::BaseService
+  #     attr_reader :id, :first_name, :last_name
+  #
+  #     validates :id, :first_name, :last_name, presence: true
+  #
+  #     def initialize(id:, first_name:, last_name:)
+  #       @id         = id
+  #       @first_name = first_name
+  #       @last_name  = last_name
+  #     end
+  #
+  #     # PUT /api/v1/someresource/:id
+  #     def call
+  #       connection.put("someresource/#{id}", first_name: first_name, last_name: last_name)
+  #     end
+  #   end
+  #
+  def connection
+    raise NotImplementedError, 'Subclasses must implement a connection method. Must return a Faraday.new object.'
+  end
+
+  # The methods below determine what type of error gets added to the errors object.
+  #
+  #   service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=bad_request, options={}>]>
+  #
+  # When using `.call!`, they map to the `exception_mapping` above, so `bad_request?` maps to `bad_request`.
+  #
+  #   exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=bad_request, options={}>]>
+  #
+  # These methods can be overridden to add more rules when an API does not respond with the relevant HTTP status code.
+  #
+  # A common occurrence is when an API returns an HTTP status code of 400 with an error message in the body for anything
+  # related to client errors, sometimes even for a resource that could not be found.
+  #
+  # It is not required to override any of these methods since all 4xx and 5xx errors add a `client_error` or
+  # `server_error` type to the errors object, respectively.
+  #
+  # While not required, handling specific errors based on their actual meaning makes for a happier development
+  # experience.
+  #
+  # You have access to the full `Farady::Response` object set to the `response` attribute, so you can use
+  # `response.status` and `response.body` to determine the type of error.
+  #
+  # Perhaps the API does not always respond with a 422 HTTP status code for unprocessable entity requests or a 404 HTTP
+  # status for resources not found.
+  #
+  #   class YourGem::BaseService < ActiveCall::Base
+  #     ...
+  #
+  #     def not_found?
+  #       response.status == 404 || (response.status == 400 && response.body['error_code'] == 'not_found')
+  #     end
+  #
+  #     def unprocessable_entity?
+  #       response.status == 422 || (response.status == 400 && response.body['error_code'] == 'not_processable')
+  #     end
+  #
+  def bad_request?
+    response.status == 400
+  end
+
+  def unauthorized?
+    response.status == 401
+  end
+
+  def forbidden?
+    response.status == 403
+  end
+
+  def not_found?
+    response.status == 404
+  end
+
+  def not_acceptable?
+    response.status == 406
+  end
+
+  def proxy_authentication_required?
+    response.status == 407
+  end
+
+  def request_timeout?
+    response.status == 408
+  end
+
+  def conflict?
+    response.status == 409
+  end
+
+  def unprocessable_entity?
+    response.status == 422
+  end
+
+  def too_many_requests?
+    response.status == 429
+  end
+
+  def internal_server_error?
+    response.status == 500
+  end
+
+  def not_implemented?
+    response.status == 501
+  end
+
+  def bad_gateway?
+    response.status == 502
+  end
+
+  def service_unavailable?
+    response.status == 503
+  end
+
+  def gateway_timeout?
+    response.status == 504
+  end
+end
+
+ActiveSupport.on_load(:i18n) do
+  I18n.load_path << File.expand_path('api/locale/en.yml', __dir__)
+end

data/lib/active_call/error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveCall
+  # 400..499
+  class ClientError < RequestError; end
+
+  # 400
+  class BadRequestError < ClientError; end
+
+  # 401
+  class UnauthorizedError < ClientError; end
+
+  # 403
+  class ForbiddenError < ClientError; end
+
+  # 404
+  class NotFoundError < ClientError; end
+
+  # 406
+  class NotAcceptableError < ClientError; end
+
+  # 407
+  class ProxyAuthenticationRequiredError < ClientError; end
+
+  # 408
+  class RequestTimeoutError < ClientError; end
+
+  # 409
+  class ConflictError < ClientError; end
+
+  # 422
+  class UnprocessableEntityError < ClientError; end
+
+  # 429
+  class TooManyRequestsError < ClientError; end
+
+  # 500..599
+  class ServerError < RequestError; end
+
+  # 500
+  class InternalServerError < ServerError; end
+
+  # 501
+  class NotImplementedError < ServerError; end
+
+  # 502
+  class BadGatewayError < ServerError; end
+
+  # 503
+  class ServiceUnavailableError < ServerError; end
+
+  # 504
+  class GatewayTimeoutError < ServerError; end
+end

data/sig/active_call/api.rbs

@@ -0,0 +1,6 @@
+module ActiveCall
+  module Api
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: active_call-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kobus Joubert
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_call
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-logging-color_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Active Call - API is an extension of Active Call that provides a standardized
+  way to create service objects for REST API endpoints.
+email:
+- kobus@translate3d.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/active_call/api.rb
+- lib/active_call/api/locale/en.yml
+- lib/active_call/api/version.rb
+- lib/active_call/error.rb
+- sig/active_call/api.rbs
+homepage: https://github.com/kobusjoubert/active_call-api
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'false'
+  homepage_uri: https://github.com/kobusjoubert/active_call-api
+  source_code_uri: https://github.com/kobusjoubert/active_call-api
+  changelog_uri: https://github.com/kobusjoubert/active_call-api/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Active Call - API
+test_files: []