api_adaptor 0.1.0 → 1.0.0

data/lib/api_adaptor/base.rb

@@ -6,20 +6,113 @@ require_relative "null_logger"
 require_relative "list_response"
 
 module ApiAdaptor
+  # Base class for building API-specific clients.
+  #
+  # Provides common functionality for JSON API clients including HTTP method delegation,
+  # URL construction, and pagination support. Subclass this to create clients for specific APIs.
+  #
+  # @example Creating a custom API client
+  #   class MyApiClient < ApiAdaptor::Base
+  #     def initialize
+  #       super("https://api.example.com", bearer_token: "abc123")
+  #     end
+  #
+  #     def get_user(id)
+  #       get_json("/users/#{id}")
+  #     end
+  #
+  #     def list_posts(page: 1)
+  #       get_list("/posts?page=#{page}")
+  #     end
+  #   end
+  #
+  # @example Using default options
+  #   ApiAdaptor::Base.default_options = { timeout: 10 }
+  #   client = MyApiClient.new  # Inherits 10-second timeout
+  #
+  # @see JSONClient for underlying HTTP client options
   class Base
+    # Raised when an invalid API URL is provided
     class InvalidAPIURL < StandardError
     end
 
     extend Forwardable
 
+    # Returns the underlying JSONClient instance, creating it if necessary
+    #
+    # @return [JSONClient] The HTTP client instance
     def client
       @client ||= create_client
     end
 
+    # Creates a new JSONClient with the configured options
+    #
+    # @return [JSONClient] A new HTTP client instance
     def create_client
       ApiAdaptor::JsonClient.new(options)
     end
 
+    # @!method get_json(url, &block)
+    #   Performs a GET request and parses JSON response
+    #   @param url [String] The URL to request
+    #   @yield [Hash] The parsed JSON response
+    #   @return [Response, Object] Response object or yielded value
+    #   @see JSONClient#get_json
+    #
+    # @!method post_json(url, params = {})
+    #   Performs a POST request with JSON body
+    #   @param url [String] The URL to request
+    #   @param params [Hash] Data to send as JSON
+    #   @return [Response] Response object
+    #   @see JSONClient#post_json
+    #
+    # @!method put_json(url, params = {})
+    #   Performs a PUT request with JSON body
+    #   @param url [String] The URL to request
+    #   @param params [Hash] Data to send as JSON
+    #   @return [Response] Response object
+    #   @see JSONClient#put_json
+    #
+    # @!method patch_json(url, params = {})
+    #   Performs a PATCH request with JSON body
+    #   @param url [String] The URL to request
+    #   @param params [Hash] Data to send as JSON
+    #   @return [Response] Response object
+    #   @see JSONClient#patch_json
+    #
+    # @!method delete_json(url, params = {})
+    #   Performs a DELETE request
+    #   @param url [String] The URL to request
+    #   @param params [Hash] Optional data to send as JSON
+    #   @return [Response] Response object
+    #   @see JSONClient#delete_json
+    #
+    # @!method get_raw(url)
+    #   Performs a GET request and returns raw response
+    #   @param url [String] The URL to request
+    #   @return [RestClient::Response] Raw response object
+    #   @see JSONClient#get_raw
+    #
+    # @!method get_raw!(url)
+    #   Performs a GET request and returns raw response, raising on errors
+    #   @param url [String] The URL to request
+    #   @return [RestClient::Response] Raw response object
+    #   @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    #   @see JSONClient#get_raw!
+    #
+    # @!method put_multipart(url, params = {})
+    #   Performs a PUT request with multipart/form-data
+    #   @param url [String] The URL to request
+    #   @param params [Hash] Multipart form data
+    #   @return [Response] Response object
+    #   @see JSONClient#put_multipart
+    #
+    # @!method post_multipart(url, params = {})
+    #   Performs a POST request with multipart/form-data
+    #   @param url [String] The URL to request
+    #   @param params [Hash] Multipart form data
+    #   @return [Response] Response object
+    #   @see JSONClient#post_multipart
     def_delegators :client,
                    :get_json,
                    :post_json,
@@ -31,17 +124,40 @@ module ApiAdaptor
                    :put_multipart,
                    :post_multipart
 
+    # @return [Hash] The client configuration options
     attr_reader :options
 
     class << self
+      # @!attribute [w] logger
+      #   Sets the default logger for all Base instances
+      #   @param value [Logger] Logger instance
       attr_writer :logger
+
+      # @!attribute [rw] default_options
+      #   Default options merged into all Base instances
+      #   @return [Hash, nil] Default options hash
       attr_accessor :default_options
     end
 
+    # Returns the default logger for Base instances
+    #
+    # @return [Logger] Logger instance (defaults to NullLogger)
     def self.logger
       @logger ||= ApiAdaptor::NullLogger.new
     end
 
+    # Initializes a new API client
+    #
+    # @param endpoint_url [String, nil] Base URL for the API
+    # @param options [Hash] Configuration options (see JSONClient#initialize for details)
+    #
+    # @raise [InvalidAPIURL] If endpoint_url is invalid
+    #
+    # @example Basic initialization
+    #   client = Base.new("https://api.example.com")
+    #
+    # @example With authentication
+    #   client = Base.new("https://api.example.com", bearer_token: "abc123")
     def initialize(endpoint_url = nil, options = {})
       options[:endpoint_url] = endpoint_url
       raise InvalidAPIURL if !endpoint_url.nil? && endpoint_url !~ URI::RFC3986_Parser::RFC3986_URI
@@ -52,10 +168,31 @@ module ApiAdaptor
       self.endpoint = options[:endpoint_url]
     end
 
+    # Constructs a URL for a given slug with query parameters
+    #
+    # @param slug [String] The API endpoint slug
+    # @param options [Hash] Query parameters to append
+    #
+    # @return [String] Full URL with .json extension and query string
+    #
+    # @example
+    #   url_for_slug("users/123", include: "posts")
+    #   # => "https://api.example.com/users/123.json?include=posts"
     def url_for_slug(slug, options = {})
       "#{base_url}/#{slug}.json#{query_string(options)}"
     end
 
+    # Performs a GET request and wraps the response in a ListResponse
+    #
+    # @param url [String] The URL to request
+    #
+    # @return [ListResponse] Paginated response wrapper
+    #
+    # @example
+    #   list = client.get_list("/posts?page=1")
+    #   list.results       # => Array of items
+    #   list.current_page  # => 1
+    #   list.total_pages   # => 10
     def get_list(url)
       get_json(url) do |r|
         ApiAdaptor::ListResponse.new(r, self)

data/lib/api_adaptor/exceptions.rb

@@ -1,25 +1,55 @@
 # frozen_string_literal: true
 
 module ApiAdaptor
-  # Abstract error class
+  # Base exception class for all ApiAdaptor errors
   class BaseError < StandardError; end
 
+  # Raised when too many redirects are followed
+  #
+  # @see JSONClient#max_redirects
   class TooManyRedirects < BaseError; end
 
+  # Raised when a redirect response is missing the Location header
   class RedirectLocationMissing < BaseError; end
 
+  # Raised when connection to the endpoint is refused (ECONNREFUSED)
   class EndpointNotFound < BaseError; end
 
+  # Raised when a request times out
+  #
+  # @see JSONClient#initialize for timeout configuration
   class TimedOutException < BaseError; end
 
+  # Raised when an invalid URL is provided
   class InvalidUrl < BaseError; end
 
+  # Raised when a socket error occurs during the request
   class SocketErrorException < BaseError; end
 
-  # Superclass for all 4XX and 5XX errors
+  # Base class for all HTTP 4xx and 5xx error responses
+  #
+  # Provides access to the HTTP status code, error details, and response body.
+  #
+  # @example Handling HTTP errors
+  #   begin
+  #     client.get_json(url)
+  #   rescue ApiAdaptor::HTTPNotFound => e
+  #     puts "Resource not found: #{e.code}"
+  #   rescue ApiAdaptor::HTTPServerError => e
+  #     puts "Server error: #{e.code} - #{e.error_details}"
+  #   end
   class HTTPErrorResponse < BaseError
+    # @return [Integer] HTTP status code
+    # @return [Hash, nil] Parsed error details from response body
+    # @return [String, nil] Raw HTTP response body
     attr_accessor :code, :error_details, :http_body
 
+    # Initializes a new HTTP error response
+    #
+    # @param code [Integer] HTTP status code
+    # @param message [String, nil] Error message
+    # @param error_details [Hash, nil] Parsed error details from JSON body
+    # @param http_body [String, nil] Raw HTTP response body
     def initialize(code, message = nil, error_details = nil, http_body = nil)
       super(message)
       @code = code
@@ -28,51 +58,84 @@ module ApiAdaptor
     end
   end
 
-  # Superclass & fallback for all 4XX errors
+  # Base class for all HTTP 4xx client errors
   class HTTPClientError < HTTPErrorResponse; end
 
+  # Base class for intermittent client errors that may succeed on retry
   class HTTPIntermittentClientError < HTTPClientError; end
 
+  # Raised on HTTP 404 Not Found
   class HTTPNotFound < HTTPClientError; end
 
+  # Raised on HTTP 410 Gone
   class HTTPGone < HTTPClientError; end
 
+  # Raised on HTTP 413 Payload Too Large
   class HTTPPayloadTooLarge < HTTPClientError; end
 
+  # Raised on HTTP 401 Unauthorized
   class HTTPUnauthorized < HTTPClientError; end
 
+  # Raised on HTTP 403 Forbidden
   class HTTPForbidden < HTTPClientError; end
 
+  # Raised on HTTP 409 Conflict
   class HTTPConflict < HTTPClientError; end
 
+  # Raised on HTTP 422 Unprocessable Entity
   class HTTPUnprocessableEntity < HTTPClientError; end
 
+  # Raised on HTTP 422 Unprocessable Content (alternative name)
   class HTTPUnprocessableContent < HTTPClientError; end
 
+  # Raised on HTTP 400 Bad Request
   class HTTPBadRequest < HTTPClientError; end
 
+  # Raised on HTTP 429 Too Many Requests
   class HTTPTooManyRequests < HTTPIntermittentClientError; end
 
-  # Superclass & fallback for all 5XX errors
+  # Base class for all HTTP 5xx server errors
   class HTTPServerError < HTTPErrorResponse; end
 
+  # Base class for intermittent server errors that may succeed on retry
   class HTTPIntermittentServerError < HTTPServerError; end
 
+  # Raised on HTTP 500 Internal Server Error
   class HTTPInternalServerError < HTTPServerError; end
 
+  # Raised on HTTP 502 Bad Gateway
   class HTTPBadGateway < HTTPIntermittentServerError; end
 
+  # Raised on HTTP 503 Service Unavailable
   class HTTPUnavailable < HTTPIntermittentServerError; end
 
+  # Raised on HTTP 504 Gateway Timeout
   class HTTPGatewayTimeout < HTTPIntermittentServerError; end
 
+  # Module providing HTTP error handling and exception mapping
   module ExceptionHandling
+    # Builds a specific HTTP error exception based on the status code
+    #
+    # @param error [RestClient::Exception] The RestClient exception
+    # @param url [String] The URL that was requested
+    # @param details [Hash, nil] Parsed error details from JSON response
+    #
+    # @return [HTTPErrorResponse] Specific exception instance
+    #
+    # @api private
     def build_specific_http_error(error, url, details = nil)
       message = "URL: #{url}\nResponse body:\n#{error.http_body}"
       code = error.http_code
       error_class_for_code(code).new(code, message, details, error.http_body)
     end
 
+    # Maps HTTP status codes to exception classes
+    #
+    # @param code [Integer] HTTP status code
+    #
+    # @return [Class] Exception class for the status code
+    #
+    # @api private
     def error_class_for_code(code)
       case code
       when 400

data/lib/api_adaptor/headers.rb

@@ -1,22 +1,54 @@
 # frozen_string_literal: true
 
 module ApiAdaptor
+  # Thread-safe header management for HTTP requests
+  #
+  # Headers are stored in thread-local storage, allowing different threads
+  # to maintain separate header contexts without interference.
+  #
+  # @example Setting custom headers
+  #   ApiAdaptor::Headers.set_header("X-Request-ID", "12345")
+  #   ApiAdaptor::Headers.set_header("X-Correlation-ID", "abcde")
+  #
+  # @example Getting all headers
+  #   headers = ApiAdaptor::Headers.headers
+  #   # => {"X-Request-ID" => "12345", "X-Correlation-ID" => "abcde"}
+  #
+  # @example Clearing headers
+  #   ApiAdaptor::Headers.clear_headers
   class Headers
     class << self
+      # Sets a header value for the current thread
+      #
+      # @param header_name [String] Header name
+      # @param value [String] Header value
+      #
+      # @return [String] The value that was set
       def set_header(header_name, value)
         header_data[header_name] = value
       end
 
+      # Returns all non-empty headers for the current thread
+      #
+      # @return [Hash] Hash of header names to values, excluding nil/empty values
       def headers
         header_data.reject { |_k, v| v.nil? || v.empty? }
       end
 
+      # Clears all headers for the current thread
+      #
+      # @return [Hash] Empty hash
       def clear_headers
         Thread.current[:headers] = {}
       end
 
       private
 
+      # Returns the thread-local header storage
+      #
+      # @return [Hash] Thread-local header hash
+      #
+      # @api private
       def header_data
         Thread.current[:headers] ||= {}
       end

data/lib/api_adaptor/json_client.rb

@@ -9,11 +9,68 @@ require_relative "response"
 require "rest-client"
 
 module ApiAdaptor
+  # HTTP client for JSON APIs with comprehensive redirect handling and authentication support.
+  #
+  # JSONClient provides a low-level interface for making HTTP requests to JSON APIs. It handles
+  # automatic JSON parsing, configurable redirect following, authentication (bearer token and basic auth),
+  # timeout management, and comprehensive error handling.
+  #
+  # @example Basic usage with bearer token
+  #   client = JSONClient.new(bearer_token: "abc123")
+  #   response = client.get_json("https://api.example.com/users")
+  #   users = response["data"]
+  #
+  # @example Custom timeout and redirect configuration
+  #   client = JSONClient.new(
+  #     timeout: 10,
+  #     max_redirects: 5,
+  #     follow_non_get_redirects: true
+  #   )
+  #
+  # @example With basic authentication
+  #   client = JSONClient.new(
+  #     basic_auth: { user: "username", password: "password" }
+  #   )
+  #
+  # @example Disable cross-origin redirects for security
+  #   client = JSONClient.new(
+  #     allow_cross_origin_redirects: false
+  #   )
+  #
+  # @see Base for a higher-level API client framework
   class JsonClient
     include ApiAdaptor::ExceptionHandling
 
+    # @return [Logger] Logger instance for request/response logging
+    # @return [Hash] Client configuration options
     attr_accessor :logger, :options
 
+    # Initializes a new JSON HTTP client
+    #
+    # @param options [Hash] Configuration options
+    # @option options [String] :bearer_token Bearer token for Authorization header
+    # @option options [Hash] :basic_auth Basic authentication credentials with :user and :password keys
+    # @option options [Integer] :timeout Request timeout in seconds (default: 4)
+    # @option options [Integer] :max_redirects Maximum number of redirects to follow (default: 3)
+    # @option options [Boolean] :allow_cross_origin_redirects Allow redirects to different origins (default: true)
+    # @option options [Boolean] :forward_auth_on_cross_origin_redirects Forward auth headers on cross-origin redirects (default: false, security risk if enabled)
+    # @option options [Boolean] :follow_non_get_redirects Follow redirects for POST/PUT/PATCH/DELETE (default: false, only 307/308 supported)
+    # @option options [Logger] :logger Custom logger instance (default: NullLogger)
+    #
+    # @raise [RuntimeError] If disable_timeout or negative timeout is provided
+    #
+    # @example Default configuration
+    #   client = JSONClient.new
+    #   # timeout: 4s, max_redirects: 3, only GET/HEAD follow redirects
+    #
+    # @example Full configuration
+    #   client = JSONClient.new(
+    #     bearer_token: "secret",
+    #     timeout: 10,
+    #     max_redirects: 5,
+    #     allow_cross_origin_redirects: false,
+    #     logger: Logger.new($stdout)
+    #   )
     def initialize(options = {})
       raise "It is no longer possible to disable the timeout." if options[:disable_timeout] || options[:timeout].to_i.negative?
 
@@ -21,6 +78,9 @@ module ApiAdaptor
       @options = options
     end
 
+    # Returns default HTTP headers for all requests
+    #
+    # @return [Hash] Default headers including Accept and User-Agent
     def self.default_request_headers
       {
         "Accept" => "application/json",
@@ -28,52 +88,161 @@ module ApiAdaptor
       }
     end
 
+    # Returns default headers for requests with JSON body
+    #
+    # @return [Hash] Default headers plus Content-Type: application/json
     def self.default_request_with_json_body_headers
       default_request_headers.merge(json_body_headers)
     end
 
+    # Returns Content-Type header for JSON requests
+    #
+    # @return [Hash] Content-Type header
     def self.json_body_headers
       {
         "Content-Type" => "application/json"
       }
     end
 
+    # Default request timeout in seconds
     DEFAULT_TIMEOUT_IN_SECONDS = 4
+
+    # Default maximum number of redirects to follow
     DEFAULT_MAX_REDIRECTS = 3
 
+    # Performs a GET request and returns the raw response
+    #
+    # @param url [String] The URL to request
+    #
+    # @return [RestClient::Response] Raw HTTP response
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    # @raise [TimedOutException] On timeout
+    # @raise [EndpointNotFound] On connection refused
+    # @raise [InvalidUrl] On invalid URI
+    # @raise [TooManyRedirects] When max_redirects is exceeded
+    # @raise [RedirectLocationMissing] When redirect lacks Location header
     def get_raw!(url)
       do_raw_request(:get, url)
     end
 
+    # Performs a GET request and returns the raw response (alias for get_raw!)
+    #
+    # @param url [String] The URL to request
+    #
+    # @return [RestClient::Response] Raw HTTP response
+    #
+    # @see #get_raw!
     def get_raw(url)
       get_raw!(url)
     end
 
+    # Performs a GET request and parses the JSON response
+    #
+    # @param url [String] The URL to request
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    # @yield [response] Optional block to create custom response object
+    # @yieldparam response [RestClient::Response] The raw HTTP response
+    # @yieldreturn [Object] Custom response object
+    #
+    # @return [Response, Object] Response object or custom object from block
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    # @raise [TimedOutException] On timeout
+    #
+    # @example Basic usage
+    #   response = client.get_json("https://api.example.com/users")
+    #   users = response["data"]
+    #
+    # @example With custom response class
+    #   users = client.get_json("https://api.example.com/users") do |r|
+    #     UserListResponse.new(r)
+    #   end
     def get_json(url, additional_headers = {}, &create_response)
       do_json_request(:get, url, nil, additional_headers, &create_response)
     end
 
+    # Performs a POST request with JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Data to send as JSON in request body (default: {})
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    #
+    # @example
+    #   response = client.post_json("https://api.example.com/users", {
+    #     name: "Alice",
+    #     email: "alice@example.com"
+    #   })
     def post_json(url, params = {}, additional_headers = {})
       do_json_request(:post, url, params, additional_headers)
     end
 
+    # Performs a PUT request with JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Data to send as JSON in request body
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
     def put_json(url, params, additional_headers = {})
       do_json_request(:put, url, params, additional_headers)
     end
 
+    # Performs a PATCH request with JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Data to send as JSON in request body
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
     def patch_json(url, params, additional_headers = {})
       do_json_request(:patch, url, params, additional_headers)
     end
 
+    # Performs a DELETE request with optional JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Optional data to send as JSON in request body (default: {})
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
     def delete_json(url, params = {}, additional_headers = {})
       do_json_request(:delete, url, params, additional_headers)
     end
 
+    # Performs a POST request with multipart/form-data
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Multipart form data (may include file uploads)
+    #
+    # @return [Response] Response object
+    #
+    # @example Uploading a file
+    #   client.post_multipart("https://api.example.com/upload", {
+    #     file: File.open("image.jpg", "rb"),
+    #     description: "Profile photo"
+    #   })
     def post_multipart(url, params)
       r = do_raw_request(:post, url, params.merge(multipart: true))
       Response.new(r)
     end
 
+    # Performs a PUT request with multipart/form-data
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Multipart form data (may include file uploads)
+    #
+    # @return [Response] Response object
     def put_multipart(url, params)
       r = do_raw_request(:put, url, params.merge(multipart: true))
       Response.new(r)
@@ -142,9 +311,9 @@ module ApiAdaptor
     def with_headers(method_params, default_headers, additional_headers)
       method_params.merge(
         headers: default_headers
-          .merge(method_params[:headers] || {})
-          .merge(ApiAdaptor::Headers.headers)
-          .merge(additional_headers)
+                 .merge(method_params[:headers] || {})
+                 .merge(ApiAdaptor::Headers.headers)
+                 .merge(additional_headers)
       )
     end