api_adaptor 0.0.2 → 1.0.0

data/README.md

@@ -1,5 +1,9 @@
 # ApiAdaptor
 
+[![CI](https://github.com/huwd/api_adaptor/actions/workflows/quality-checks.yml/badge.svg)](https://github.com/huwd/api_adaptor/actions/workflows/quality-checks.yml)
+[![Gem Version](https://badge.fury.io/rb/api_adaptor.svg)](https://badge.fury.io/rb/api_adaptor)
+[![Documentation](https://img.shields.io/badge/docs-YARD-blue.svg)](https://huwd.github.io/api_adaptor/)
+
 A basic adaptor to send HTTP requests and parse the responses.
 Intended to bootstrap the quick writing of Adaptors for specific APIs, without having to write the same old JSON request and processing time and time again.
 
@@ -17,64 +21,177 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install api_adaptor
 ```
 
+## API Documentation
+
+Full API documentation is available at [https://huwd.github.io/api_adaptor/](https://huwd.github.io/api_adaptor/)
+
+Generate documentation locally:
+
+```bash
+bundle exec yard         # Generate docs to doc/
+bundle exec yard server  # Preview at http://localhost:8808
+```
+
+## Releasing
+
+Publishing is handled by GitHub Actions when you push a version tag.
+
+- RubyGems publishing uses **Trusted Publishing (OIDC)** via `rubygems/release-gem`
+- Ensure `api_adaptor` is configured on RubyGems.org with this repository/workflow as a trusted publisher.
+- Bump `ApiAdaptor::VERSION` in `lib/api_adaptor/version.rb`.
+- Tag the release as `vX.Y.Z` (must match `ApiAdaptor::VERSION`) and push the tag:
+
+```shell
+git tag v0.1.1
+git push origin v0.1.1
+```
+
 ## Usage
 
 Use the ApiAdaptor as a base class for your API wrapper, for example:
 
 ```ruby
-  class MyApi < ApiAdaptor::Base
-    def base_url
-      endpoint
-    end
-  end
+  class MyApi < ApiAdaptor::Base; end
 ```
 
 Use your new class to create a client that can make HTTP requests to JSON APIs for:
 
-### GET JSON
-
 ```ruby
 client = MyApi.new
-response = client.get_json("http://some.endpoint/json")
+client.get_json("http://some.endpoint/json")
+client.post_json("http://some.endpoint/json", { "foo": "bar" })
+client.put_json("http://some.endpoint/json", { "foo": "bar" })
+client.patch_json("http://some.endpoint/json", { "foo": "bar" })
+client.delete_json("http://some.endpoint/json", { "foo": "bar" })
 ```
 
-### POST JSON
+You can also get a raw response from the API
 
 ```ruby
-client = MyApi.new
-response = client.post_json("http://some.endpoint/json", { "foo": "bar" })
+client.get_raw("http://some.endpoint/json")
+```
+
+### Redirects (3xx)
+
+Some APIs return a `3xx` response (commonly `307`/`308`) with a `Location` header that points to the “real” URL.
+`ApiAdaptor::JsonClient` follows these redirects in a controlled way so callers consistently receive a final JSON response.
+
+#### Defaults
+
+- Redirects are followed for `GET`/`HEAD` when the status is `301`, `302`, `303`, `307`, or `308`.
+- `max_redirects` defaults to `3`.
+- Cross-origin redirects (scheme/host/port change) are allowed by default, but credentials are **not** forwarded.
+- Non-GET requests (`POST`, `PUT`, `PATCH`, `DELETE`) do **not** follow redirects by default.
+
+#### Configuration
+
+You can configure redirect behaviour by passing options into your `ApiAdaptor::Base` subclass (they are forwarded to `ApiAdaptor::JsonClient`):
+
+```ruby
+client = MyApi.new(
+  "https://example.com",
+  max_redirects: 3,
+  allow_cross_origin_redirects: true,
+  forward_auth_on_cross_origin_redirects: false,
+  follow_non_get_redirects: false
+)
+
+client.get_json("https://example.com/some/endpoint.json")
 ```
 
-### PUT JSON
+Or, if you are using `ApiAdaptor::JsonClient` directly:
 
 ```ruby
-client = MyApi.new
-response = client.put_json("http://some.endpoint/json", { "foo": "bar" })
+client = ApiAdaptor::JsonClient.new(
+  bearer_token: "SOME_BEARER_TOKEN",
+  max_redirects: 3,
+  allow_cross_origin_redirects: true,
+  forward_auth_on_cross_origin_redirects: false
+)
+
+client.get_json("https://example.com/some/endpoint.json")
 ```
 
-### PATCH JSON
+#### Security: auth and cross-origin redirects
+
+Following redirects across origins can accidentally leak credentials (for example `Authorization` bearer tokens) to an unexpected host.
+To reduce risk:
+
+- By default, when the redirect target is cross-origin, `Authorization` is stripped and basic auth is not applied.
+- To completely prevent cross-origin redirects, set `allow_cross_origin_redirects: false`.
+- Only set `forward_auth_on_cross_origin_redirects: true` if you fully trust the redirect target.
+
+#### Non-GET redirects (risk of replay)
+
+Redirects for non-GET requests are risky because they may cause a request to be replayed (and potentially create duplicate side effects).
+For that reason, redirect-following is disabled for non-GET requests by default.
+
+If you do want to follow `307`/`308` for non-GET requests, you can opt in:
 
 ```ruby
-client = MyApi.new
-response = client.patch_json("http://some.endpoint/json", { "foo": "bar" })
+client = MyApi.new(
+  "https://example.com",
+  follow_non_get_redirects: true
+)
+
+client.post_json("https://example.com/some/endpoint.json", { "a" => 1 })
 ```
 
-### DELETE JSON
+#### Handling redirect failures
+
+You can rescue these redirect-specific exceptions:
+
+- `ApiAdaptor::TooManyRedirects` (exceeded `max_redirects`)
+- `ApiAdaptor::RedirectLocationMissing` (a redirect response without a usable `Location`)
+
+Example:
 
 ```ruby
-client = MyApi.new
-response = client.delete_json("http://some.endpoint/json", { "foo": "bar" })
+begin
+  client.get_json("https://example.com/some/endpoint.json")
+rescue ApiAdaptor::TooManyRedirects, ApiAdaptor::RedirectLocationMissing => e
+  # handle / log / retry / surface a friendly message
+  raise e
+end
 ```
 
-### GET raw requests
+### Conventional usage
+
+An example of how to use this repository to bootstrap an API can be found in the [WikiData REST adaptor](https://github.com/huwd/wikidata_adaptor) it was built for.
 
-you can also get a raw response from the API
+A REST API module can be created with:
 
 ```ruby
-client = MyApi.new
-response = client.get_raw("http://some.endpoint/json")
+module MyApiAdaptor
+  # Wikidata REST API class
+  class RestApi < ApiAdaptor::Base
+    def get_foo(foo_id)
+      get_json("#{endpoint}/foo/#{CGI.escape(foo_id)}")
+    end
+  end
+end
 ```
 
+and can be wrapped in a top level module:
+
+```ruby
+module MyApiAdaptor
+  class Error < StandardError; end
+
+  def self.rest_endpoint
+    ENV["MYAPI_REST_ENDPOINT"] || "https://example.com"
+  end
+
+  def self.rest_api
+    MyApiAdaptor::RestApi.new(rest_endpoint)
+  end
+end
+```
+
+The intended convention is to have test helpers ship alongside the actual Adaptor code.
+See [WikiData examples here](https://github.com/huwd/wikidata_adaptor/blob/main/lib/wikidata_adaptor/test_helpers/rest_api.rb).
+This allows other applications that integrate the API Adaptor to easily mock out calls and receive representative data back.
+
 ## Environment variables
 
 User Agent is populated with a default string.
@@ -94,6 +211,76 @@ User agent would read
 test_app/1.0.0 (contact@example.com)
 ```
 
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+### Running Tests
+
+```bash
+bundle exec rspec        # Run tests only
+bundle exec rubocop      # Run linter only
+bundle exec rake         # Run tests, linter, and build docs
+```
+
+### Code Coverage
+
+SimpleCov tracks test coverage. View the report at `coverage/index.html` after running tests.
+
+Current coverage: 92.3% line, 81.65% branch
+
+### Documentation
+
+Generate YARD documentation:
+
+```bash
+bundle exec yard         # Generate docs to doc/
+bundle exec yard server  # Preview at http://localhost:8808
+bundle exec yard stats   # View documentation coverage
+```
+
+### Quality Standards
+
+- **Tests:** RSpec with WebMock for HTTP mocking
+- **Linting:** RuboCop with rubocop-yard for documentation
+- **Coverage:** SimpleCov (minimum 80% line, 75% branch)
+- **Documentation:** YARD for all public APIs
+
+## Troubleshooting
+
+### Redirects Not Following
+
+By default, only GET/HEAD requests follow redirects. For POST/PUT/PATCH/DELETE:
+
+```ruby
+client = MyApi.new("https://example.com", follow_non_get_redirects: true)
+```
+
+### Timeout Errors
+
+Default timeout is 4 seconds. Configure longer timeouts:
+
+```ruby
+client = MyApi.new("https://example.com", timeout: 10)
+```
+
+### Cross-Origin Redirect Security
+
+By default, auth headers are stripped on cross-origin redirects. To allow (use with caution):
+
+```ruby
+client = MyApi.new(
+  "https://example.com",
+  forward_auth_on_cross_origin_redirects: true  # Security risk!
+)
+```
+
+Or disable cross-origin redirects entirely:
+
+```ruby
+client = MyApi.new("https://example.com", allow_cross_origin_redirects: false)
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/huwd/api_adaptor>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/huwd/api_adaptor/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -9,4 +9,10 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+require "yard"
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.stats_options = ["--list-undoc"]
+end
+
+task default: %i[spec rubocop yard]

data/fixtures/v1/integration/foo.json

@@ -0,0 +1,3 @@
+{
+  "foo": "bar"
+}

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,20 +124,43 @@ 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
 
-    def initialize(endpoint_url, options = {})
+    # 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 unless endpoint_url =~ URI::RFC3986_Parser::RFC3986_URI
+      raise InvalidAPIURL if !endpoint_url.nil? && endpoint_url !~ URI::RFC3986_Parser::RFC3986_URI
 
       base_options = { logger: ApiAdaptor::Base.logger }
       default_options = base_options.merge(ApiAdaptor::Base.default_options || {})
@@ -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,21 +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
@@ -24,49 +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