api_adaptor 0.0.0 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30c6b5be3dca0a584c80707e773dcaf88a16588cae895628836d45298fa6bb34
-  data.tar.gz: b394a5354f56e56d6c39c4b86e2f960ba8916578008280e7aee189b80d5bb371
+  metadata.gz: d434d1287d28256b67543919c32dba816a5c6a682247108a985eee72ac7ca86c
+  data.tar.gz: e386558347941960b7c54bbd0107381202bfcf4c8318c0ac3908cf2bd3e1c99a
 SHA512:
-  metadata.gz: e48b671f2f25ac38b79afaf9b11ab06053b133f66a6df0f373070c2b101eacab5e4820833d8d3b440e8ff08bc96cde8b97c3ab70e54a21501a82776efeae9323
-  data.tar.gz: 42c84ad34fb77d684dcf9e6f897b5865988502c95cb9959b851c02fe415382d9cee84a15606e66a017e28f37962ef500354cb4bb2c4dc3f3a24dc174ae9cb977
+  metadata.gz: 3ee873a96fa726a95caf41861a683abc276571b3a6424ae44f7ede1c0cc27e242de879b7f8f73930f10c0347d60ff6d31595ba55235a5be1a39e36208359e524
+  data.tar.gz: 0a42e0ded563c8f1b9cab2433c8f3f5ca5160da8df923deb80382ecb3736012fa0a136d53799b4681011f6723c18eceaf5fd9e3e2ee853071ca4d38a9903b1ba

data/.env.example

@@ -0,0 +1,3 @@
+APP_NAME=
+APP_VERSION=
+APP_CONTACT=

data/.rubocop.yml

@@ -11,3 +11,12 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+Metrics:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
-## [0.0.0] - 2023-05-29
+## [0.0.1] - 2023-06-01
 
 - Initial release
+
+## [0.0.0] - 2023-05-29
+
+- Bootstrapping

data/Gemfile

@@ -4,9 +4,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in api_adaptor.gemspec
 gemspec
-
-gem "rake", "~> 13.0"
-
-gem "rspec", "~> 3.0"
-
-gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -0,0 +1,91 @@
+PATH
+  remote: .
+  specs:
+    api_adaptor (0.0.2)
+      addressable (~> 2.8)
+      link_header (~> 0.0.8)
+      rest-client (~> 2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    ast (2.4.2)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.5.0)
+    domain_name (0.6.20240107)
+    hashdiff (1.1.0)
+    http-accept (1.7.0)
+    http-cookie (1.0.5)
+      domain_name (~> 0.5)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    link_header (0.0.8)
+    mime-types (3.5.2)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2023.1205)
+    netrc (0.11.0)
+    parallel (1.24.0)
+    parser (3.3.0.3)
+      ast (~> 2.4.1)
+      racc
+    public_suffix (5.0.4)
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.1.0)
+    regexp_parser (2.9.0)
+    rest-client (2.1.0)
+      http-accept (>= 1.7.0, < 2.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rexml (3.2.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.59.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    ruby-progressbar (1.13.0)
+    timecop (0.9.8)
+    unicode-display_width (2.5.0)
+    webmock (3.19.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  api_adaptor!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  timecop (~> 0.9)
+  webmock (~> 3.18)
+
+BUNDLED WITH
+   2.4.13

data/README.md

@@ -7,19 +7,96 @@ Intended to bootstrap the quick writing of Adaptors for specific APIs, without h
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add api_adaptor
+```shell
+bundle add api_adaptor
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install api_adaptor
+```shell
+gem install api_adaptor
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Use the ApiAdaptor as a base class for your API wrapper, for example:
+
+```ruby
+  class MyApi < ApiAdaptor::Base
+    def base_url
+      endpoint
+    end
+  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")
+```
+
+### POST JSON
+
+```ruby
+client = MyApi.new
+response = client.post_json("http://some.endpoint/json", { "foo": "bar" })
+```
+
+### PUT JSON
+
+```ruby
+client = MyApi.new
+response = client.put_json("http://some.endpoint/json", { "foo": "bar" })
+```
+
+### PATCH JSON
+
+```ruby
+client = MyApi.new
+response = client.patch_json("http://some.endpoint/json", { "foo": "bar" })
+```
+
+### DELETE JSON
+
+```ruby
+client = MyApi.new
+response = client.delete_json("http://some.endpoint/json", { "foo": "bar" })
+```
+
+### GET raw requests
+
+you can also get a raw response from the API
+
+```ruby
+client = MyApi.new
+response = client.get_raw("http://some.endpoint/json")
+```
+
+## Environment variables
+
+User Agent is populated with a default string.
+See .env.example.
+
+For instance if you provide:
+
+```bash
+APP_NAME=test_app
+APP_VERSION=1.0.0
+APP_CONTACT=contact@example.com
+```
+
+User agent would read
+
+```text
+test_app/1.0.0 (contact@example.com)
+```
 
 ## 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).
+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).
 
 ## License
 

data/lib/api_adaptor/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "json_client"
+require "cgi"
+require_relative "null_logger"
+require_relative "list_response"
+
+module ApiAdaptor
+  class Base
+    class InvalidAPIURL < StandardError
+    end
+
+    extend Forwardable
+
+    def client
+      @client ||= create_client
+    end
+
+    def create_client
+      ApiAdaptor::JsonClient.new(options)
+    end
+
+    def_delegators :client,
+                   :get_json,
+                   :post_json,
+                   :put_json,
+                   :patch_json,
+                   :delete_json,
+                   :get_raw,
+                   :get_raw!,
+                   :put_multipart,
+                   :post_multipart
+
+    attr_reader :options
+
+    class << self
+      attr_writer :logger
+      attr_accessor :default_options
+    end
+
+    def self.logger
+      @logger ||= ApiAdaptor::NullLogger.new
+    end
+
+    def initialize(endpoint_url, options = {})
+      options[:endpoint_url] = endpoint_url
+      raise InvalidAPIURL unless endpoint_url =~ URI::RFC3986_Parser::RFC3986_URI
+
+      base_options = { logger: ApiAdaptor::Base.logger }
+      default_options = base_options.merge(ApiAdaptor::Base.default_options || {})
+      @options = default_options.merge(options)
+      self.endpoint = options[:endpoint_url]
+    end
+
+    def url_for_slug(slug, options = {})
+      "#{base_url}/#{slug}.json#{query_string(options)}"
+    end
+
+    def get_list(url)
+      get_json(url) do |r|
+        ApiAdaptor::ListResponse.new(r, self)
+      end
+    end
+
+    private
+
+    attr_accessor :endpoint
+
+    def query_string(params)
+      return "" if params.empty?
+
+      param_pairs = params.sort.map do |key, value|
+        case value
+        when Array
+          value.map do |v|
+            "#{CGI.escape("#{key}[]")}=#{CGI.escape(v.to_s)}"
+          end
+        else
+          "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+        end
+      end.flatten
+
+      "?#{param_pairs.join("&")}"
+    end
+
+    def uri_encode(param)
+      Addressable::URI.encode(param.to_s)
+    end
+  end
+end

data/lib/api_adaptor/exceptions.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ApiAdaptor
+  # Abstract error class
+  class BaseError < StandardError; end
+
+  class EndpointNotFound < BaseError; end
+
+  class TimedOutException < BaseError; end
+
+  class InvalidUrl < BaseError; end
+
+  class SocketErrorException < BaseError; end
+
+  # Superclass for all 4XX and 5XX errors
+  class HTTPErrorResponse < BaseError
+    attr_accessor :code, :error_details, :http_body
+
+    def initialize(code, message = nil, error_details = nil, http_body = nil)
+      super(message)
+      @code = code
+      @error_details = error_details
+      @http_body = http_body
+    end
+  end
+
+  # Superclass & fallback for all 4XX errors
+  class HTTPClientError < HTTPErrorResponse; end
+
+  class HTTPIntermittentClientError < HTTPClientError; end
+
+  class HTTPNotFound < HTTPClientError; end
+
+  class HTTPGone < HTTPClientError; end
+
+  class HTTPPayloadTooLarge < HTTPClientError; end
+
+  class HTTPUnauthorized < HTTPClientError; end
+
+  class HTTPForbidden < HTTPClientError; end
+
+  class HTTPConflict < HTTPClientError; end
+
+  class HTTPUnprocessableEntity < HTTPClientError; end
+
+  class HTTPBadRequest < HTTPClientError; end
+
+  class HTTPTooManyRequests < HTTPIntermittentClientError; end
+
+  # Superclass & fallback for all 5XX errors
+  class HTTPServerError < HTTPErrorResponse; end
+
+  class HTTPIntermittentServerError < HTTPServerError; end
+
+  class HTTPInternalServerError < HTTPServerError; end
+
+  class HTTPBadGateway < HTTPIntermittentServerError; end
+
+  class HTTPUnavailable < HTTPIntermittentServerError; end
+
+  class HTTPGatewayTimeout < HTTPIntermittentServerError; end
+
+  module ExceptionHandling
+    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
+
+    def error_class_for_code(code)
+      case code
+      when 400
+        ApiAdaptor::HTTPBadRequest
+      when 401
+        ApiAdaptor::HTTPUnauthorized
+      when 403
+        ApiAdaptor::HTTPForbidden
+      when 404
+        ApiAdaptor::HTTPNotFound
+      when 409
+        ApiAdaptor::HTTPConflict
+      when 410
+        ApiAdaptor::HTTPGone
+      when 413
+        ApiAdaptor::HTTPPayloadTooLarge
+      when 422
+        ApiAdaptor::HTTPUnprocessableEntity
+      when 429
+        ApiAdaptor::HTTPTooManyRequests
+      when (400..499)
+        ApiAdaptor::HTTPClientError
+      when 500
+        ApiAdaptor::HTTPInternalServerError
+      when 502
+        ApiAdaptor::HTTPBadGateway
+      when 503
+        ApiAdaptor::HTTPUnavailable
+      when 504
+        ApiAdaptor::HTTPGatewayTimeout
+      when (500..599)
+        ApiAdaptor::HTTPServerError
+      else
+        ApiAdaptor::HTTPErrorResponse
+      end
+    end
+  end
+end

data/lib/api_adaptor/headers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ApiAdaptor
+  class Headers
+    class << self
+      def set_header(header_name, value)
+        header_data[header_name] = value
+      end
+
+      def headers
+        header_data.reject { |_k, v| v.nil? || v.empty? }
+      end
+
+      def clear_headers
+        Thread.current[:headers] = {}
+      end
+
+      private
+
+      def header_data
+        Thread.current[:headers] ||= {}
+      end
+    end
+  end
+end

data/lib/api_adaptor/json_client.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "exceptions"
+require_relative "variables"
+require_relative "null_logger"
+require_relative "headers"
+require_relative "response"
+
+require "rest-client"
+
+module ApiAdaptor
+  class JsonClient
+    include ApiAdaptor::ExceptionHandling
+
+    attr_accessor :logger, :options
+
+    def initialize(options = {})
+      raise "It is no longer possible to disable the timeout." if options[:disable_timeout] || options[:timeout].to_i.negative?
+
+      @logger = options[:logger] || NullLogger.new
+      @options = options
+    end
+
+    def self.default_request_headers
+      {
+        "Accept" => "application/json",
+        "User-Agent" => "#{Variables.app_name}/#{Variables.app_version} (#{Variables.app_contact})"
+      }
+    end
+
+    def self.default_request_with_json_body_headers
+      default_request_headers.merge(json_body_headers)
+    end
+
+    def self.json_body_headers
+      {
+        "Content-Type" => "application/json"
+      }
+    end
+
+    DEFAULT_TIMEOUT_IN_SECONDS = 4
+
+    def get_raw!(url)
+      do_raw_request(:get, url)
+    end
+
+    def get_raw(url)
+      get_raw!(url)
+    end
+
+    def get_json(url, additional_headers = {}, &create_response)
+      do_json_request(:get, url, nil, additional_headers, &create_response)
+    end
+
+    def post_json(url, params = {}, additional_headers = {})
+      do_json_request(:post, url, params, additional_headers)
+    end
+
+    def put_json(url, params, additional_headers = {})
+      do_json_request(:put, url, params, additional_headers)
+    end
+
+    def patch_json(url, params, additional_headers = {})
+      do_json_request(:patch, url, params, additional_headers)
+    end
+
+    def delete_json(url, params = {}, additional_headers = {})
+      do_json_request(:delete, url, params, additional_headers)
+    end
+
+    def post_multipart(url, params)
+      r = do_raw_request(:post, url, params.merge(multipart: true))
+      Response.new(r)
+    end
+
+    def put_multipart(url, params)
+      r = do_raw_request(:put, url, params.merge(multipart: true))
+      Response.new(r)
+    end
+
+    private
+
+    def do_raw_request(method, url, params = nil)
+      do_request(method, url, params)
+    rescue RestClient::Exception => e
+      raise build_specific_http_error(e, url, nil)
+    end
+
+    # method: the symbolic name of the method to use, e.g. :get, :post
+    # url:    the request URL
+    # params: the data to send (JSON-serialised) in the request body
+    # additional_headers: headers to set on the request (in addition to the default ones)
+    # create_response: optional block to instantiate a custom response object
+    #                  from the Net::HTTPResponse
+    def do_json_request(method, url, params = nil, additional_headers = {}, &create_response)
+      begin
+        additional_headers.merge!(self.class.json_body_headers) if params
+        response = do_request(method, url, (params.to_json if params), additional_headers)
+      rescue RestClient::Exception => e
+        # Attempt to parse the body as JSON if possible
+        error_details = begin
+          e.http_body ? JSON.parse(e.http_body) : nil
+        rescue JSON::ParserError
+          nil
+        end
+        raise build_specific_http_error(e, url, error_details)
+      end
+
+      # If no custom response is given, just instantiate Response
+      create_response ||= proc { |r| Response.new(r) }
+      create_response.call(response)
+    end
+
+    # Take a hash of parameters for Request#execute; return a hash of
+    # parameters with authentication information included
+    def with_auth_options(method_params)
+      if @options[:bearer_token]
+        headers = method_params[:headers] || {}
+        method_params.merge(headers: headers.merge(
+          "Authorization" => "Bearer #{@options[:bearer_token]}"
+        ))
+      elsif @options[:basic_auth]
+        method_params.merge(
+          user: @options[:basic_auth][:user],
+          password: @options[:basic_auth][:password]
+        )
+      else
+        method_params
+      end
+    end
+
+    # Take a hash of parameters for Request#execute; return a hash of
+    # parameters with timeouts included
+    def with_timeout(method_params)
+      method_params.merge(
+        timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS,
+        open_timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS
+      )
+    end
+
+    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)
+      )
+    end
+
+    def with_ssl_options(method_params)
+      method_params.merge(
+        # This is the default value anyway, but we should probably be explicit
+        verify_ssl: OpenSSL::SSL::VERIFY_NONE
+      )
+    end
+
+    def do_request(method, url, params = nil, additional_headers = {})
+      loggable = { request_uri: url, start_time: Time.now.to_f }
+      start_logging = loggable.merge(action: "start")
+      logger.debug start_logging.to_json
+
+      method_params = {
+        method: method,
+        url: url
+      }
+
+      method_params[:payload] = params
+      method_params = with_timeout(method_params)
+      method_params = with_headers(method_params, self.class.default_request_headers, additional_headers)
+      method_params = with_auth_options(method_params)
+      method_params = with_ssl_options(method_params) if URI.parse(url).is_a? URI::HTTPS
+
+      ::RestClient::Request.execute(method_params)
+    rescue Errno::ECONNREFUSED => e
+      logger.error loggable.merge(status: "refused", error_message: e.message, error_class: e.class.name,
+                                  end_time: Time.now.to_f).to_json
+      raise ApiAdaptor::EndpointNotFound, "Could not connect to #{url}"
+    rescue RestClient::Exceptions::Timeout => e
+      logger.error loggable.merge(status: "timeout", error_message: e.message, error_class: e.class.name,
+                                  end_time: Time.now.to_f).to_json
+      raise ApiAdaptor::TimedOutException, e.message
+    rescue URI::InvalidURIError => e
+      logger.error loggable.merge(status: "invalid_uri", error_message: e.message, error_class: e.class.name,
+                                  end_time: Time.now.to_f).to_json
+      raise ApiAdaptor::InvalidUrl, e.message
+    rescue RestClient::Exception => e
+      # Log the error here, since we have access to loggable, but raise the
+      # exception up to the calling method to deal with
+      loggable.merge!(status: e.http_code, end_time: Time.now.to_f, body: e.http_body)
+      logger.warn loggable.to_json
+      raise
+    rescue Errno::ECONNRESET => e
+      logger.error loggable.merge(status: "connection_reset", error_message: e.message, error_class: e.class.name,
+                                  end_time: Time.now.to_f).to_json
+      raise ApiAdaptor::TimedOutException, e.message
+    rescue SocketError => e
+      logger.error loggable.merge(status: "socket_error", error_message: e.message, error_class: e.class.name,
+                                  end_time: Time.now.to_f).to_json
+      raise ApiAdaptor::SocketErrorException, e.message
+    end
+  end
+end

data/lib/api_adaptor/list_response.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "api_adaptor/response"
+require "link_header"
+
+module ApiAdaptor
+  # Response class for lists of multiple items.
+  #
+  # This expects responses to be in a common format, with the list of results
+  # contained under the `results` key. The response may also have previous and
+  # subsequent pages, indicated by entries in the response's `Link` header.
+  class ListResponse < Response
+    # The ListResponse is instantiated with a reference back to the API client,
+    # so it can make requests for the subsequent pages
+    def initialize(response, api_client, options = {})
+      super(response, options)
+      @api_client = api_client
+    end
+
+    # Pass calls to `self.each` to the `results` sub-object, so we can iterate
+    # over the response directly
+    def_delegators :results, :each, :to_ary
+
+    def results
+      to_hash["results"]
+    end
+
+    def next_page?
+      !page_link("next").nil?
+    end
+
+    def next_page
+      # This shouldn't be a performance problem, since the cache will generally
+      # avoid us making multiple requests for the same page, but we shouldn't
+      # allow the data to change once it's already been loaded, so long as we
+      # retain a reference to any one page in the sequence
+      @next_page ||= (@api_client.get_list page_link("next").href if next_page?)
+    end
+
+    def previous_page?
+      !page_link("previous").nil?
+    end
+
+    def previous_page
+      # See the note in `next_page` for why this is memoised
+      @previous_page ||= (@api_client.get_list(page_link("previous").href) if previous_page?)
+    end
+
+    # Transparently get all results across all pages. Compare this with #each
+    # or #results which only iterate over the current page.
+    #
+    # Example:
+    #
+    #   list_response.with_subsequent_pages.each do |result|
+    #     ...
+    #   end
+    #
+    # or:
+    #
+    #   list_response.with_subsequent_pages.count
+    #
+    # Pages of results are fetched on demand. When iterating, that means
+    # fetching pages as results from the current page are exhausted. If you
+    # invoke a method such as #count, this method will fetch all pages at that
+    # point. Note that the responses are stored so subsequent pages will not be
+    # loaded multiple times.
+    def with_subsequent_pages
+      Enumerator.new do |yielder|
+        each { |i| yielder << i }
+        next_page.with_subsequent_pages.each { |i| yielder << i } if next_page?
+      end
+    end
+
+    private
+
+    def link_header
+      @link_header ||= LinkHeader.parse @http_response.headers[:link]
+    end
+
+    def page_link(rel)
+      link_header.find_link(["rel", rel])
+    end
+  end
+end

data/lib/api_adaptor/null_logger.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Null logger class. This is essentially the same as sending data down the
+# `/dev/null` black hole.
+#
+# @example Basic Usage
+#
+#   logger = NullLogger.new
+#   Rails.logger = logger
+#
+#
+# @example Basic Pattern Usage
+#   class SomeService
+#     def initialize(options = {})
+#       @logger = options[:logger] || NullLogger.new
+#     end
+#
+#     def perform
+#       @logger.debug -> { "do some work here" }
+#       # .. ..
+#       @logger.info -> { "finished working" }
+#     end
+#   end
+#
+#   service = SomeService.new(logger: Logger.new(STDOUT))
+#   service.perform
+#
+#   silent = SomeService.new(logger: NullLogger.new
+#   silent.perform
+#
+module ApiAdaptor
+  class NullLogger
+    # @param _args Anything that we want to ignore
+    # @return [nil]
+    def unknown(*_args)
+      nil
+    end
+
+    # @param _args Anything that we want to ignore
+    # @return [nil]
+    def fatal(*_args)
+      nil
+    end
+
+    # @return [FALSE]
+    def fatal?
+      false
+    end
+
+    # @param _args Anything that we want to ignore
+    # @return [nil]
+    def error(*_args)
+      nil
+    end
+
+    # @return [FALSE]
+    def error?
+      false
+    end
+
+    # @param _args Anything that we want to ignore
+    # @return [nil]
+    def warn(*_args)
+      nil
+    end
+
+    # @return [FALSE]
+    def warn?
+      false
+    end
+
+    # @param _args Anything that we want to ignore
+    # @return [nil]
+    def info(*_args)
+      nil
+    end
+
+    # @return [FALSE]
+    def info?
+      false
+    end
+
+    # @param _args Anything that we want to ignore
+    # @return [nil]
+    def debug(*_args)
+      nil
+    end
+
+    # @return [FALSE]
+    def debug?
+      false
+    end
+  end
+end

data/lib/api_adaptor/response.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "json"
+require "forwardable"
+
+module ApiAdaptor
+  # This wraps an HTTP response with a JSON body.
+  #
+  # Responses can be configured to use relative URLs for `web_url` properties.
+  # API endpoints should return absolute URLs so that they make sense outside of the
+  # domain context. However on systems within an API we want to present relative URLs.
+  # By specifying a base URI, this will convert all matching web_urls into relative URLs
+  # This is useful on non-canonical frontends, such as those in staging environments.
+  #
+  # Example:
+  #
+  #   r = Response.new(response, web_urls_relative_to: "https://www.gov.uk")
+  #   r['results'][0]['web_url']
+  #   => "/bank-holidays"
+  class Response
+    extend Forwardable
+    include Enumerable
+
+    class CacheControl < Hash
+      PATTERN = /([-a-z]+)(?:\s*=\s*([^,\s]+))?,?+/i.freeze
+
+      def initialize(value = nil)
+        super()
+        parse(value)
+      end
+
+      def public?
+        self["public"]
+      end
+
+      def private?
+        self["private"]
+      end
+
+      def no_cache?
+        self["no-cache"]
+      end
+
+      def no_store?
+        self["no-store"]
+      end
+
+      def must_revalidate?
+        self["must-revalidate"]
+      end
+
+      def proxy_revalidate?
+        self["proxy-revalidate"]
+      end
+
+      def max_age
+        self["max-age"].to_i if key?("max-age")
+      end
+
+      def reverse_max_age
+        self["r-maxage"].to_i if key?("r-maxage")
+      end
+      alias r_maxage reverse_max_age
+
+      def shared_max_age
+        self["s-maxage"].to_i if key?("r-maxage")
+      end
+      alias s_maxage shared_max_age
+
+      def to_s
+        directives = []
+        values = []
+
+        each do |key, value|
+          if value == true
+            directives << key
+          elsif value
+            values << "#{key}=#{value}"
+          end
+        end
+
+        (directives.sort + values.sort).join(", ")
+      end
+
+      private
+
+      def parse(header)
+        return if header.nil? || header.empty?
+
+        header.scan(PATTERN).each do |name, value|
+          self[name.downcase] = value || true
+        end
+      end
+    end
+
+    def_delegators :to_hash, :[], :"<=>", :each, :dig
+
+    def initialize(http_response, options = {})
+      @http_response = http_response
+      @web_urls_relative_to = options[:web_urls_relative_to] ? URI.parse(options[:web_urls_relative_to]) : nil
+    end
+
+    def raw_response_body
+      @http_response.body
+    end
+
+    def code
+      # Return an integer code for consistency with HTTPErrorResponse
+      @http_response.code
+    end
+
+    def headers
+      @http_response.headers
+    end
+
+    def expires_at
+      if headers[:date] && cache_control.max_age
+        response_date = Time.parse(headers[:date])
+        response_date + cache_control.max_age
+      elsif headers[:expires]
+        Time.parse(headers[:expires])
+      end
+    end
+
+    def expires_in
+      return unless headers[:date]
+
+      age = Time.now.utc - Time.parse(headers[:date])
+
+      if cache_control.max_age
+        cache_control.max_age - age.to_i
+      elsif headers[:expires]
+        Time.parse(headers[:expires]).to_i - Time.now.utc.to_i
+      end
+    end
+
+    def cache_control
+      @cache_control ||= CacheControl.new(headers[:cache_control])
+    end
+
+    def to_hash
+      parsed_content
+    end
+
+    def parsed_content
+      @parsed_content ||= transform_parsed(JSON.parse(@http_response.body))
+    end
+
+    def present?
+      true
+    end
+
+    def blank?
+      false
+    end
+
+    private
+
+    def transform_parsed(value)
+      return value if @web_urls_relative_to.nil?
+
+      case value
+      when Hash
+        Hash[value.map do |k, v|
+          # NOTE: Don't bother transforming if the value is nil
+          if k == "web_url" && v
+            # Use relative URLs to route when the web_url value is on the
+            # same domain as the site root. Note that we can't just use the
+            # `route_to` method, as this would give us technically correct
+            # but potentially confusing `//host/path` URLs for URLs with the
+            # same scheme but different hosts.
+            relative_url = @web_urls_relative_to.route_to(v)
+            [k, relative_url.host ? v : relative_url.to_s]
+          else
+            [k, transform_parsed(v)]
+          end
+        end]
+      when Array
+        value.map { |v| transform_parsed(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/api_adaptor/variables.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ApiAdaptor
+  module Variables
+    def self.app_name
+      ENV["APP_NAME"] || "Ruby ApiAdaptor App"
+    end
+
+    def self.app_version
+      ENV["APP_VERSION"] || "Version not stated"
+    end
+
+    def self.app_contact
+      ENV["APP_CONTACT"] || "Contact not stated"
+    end
+  end
+end

data/lib/api_adaptor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiAdaptor
-  VERSION = "0.0.0"
+  VERSION = "0.0.2"
 end

data/lib/api_adaptor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "api_adaptor/version"
+require_relative "api_adaptor/base"
 
 module ApiAdaptor
   class Error < StandardError; end

metadata

@@ -1,15 +1,127 @@
 --- !ruby/object:Gem::Specification
 name: api_adaptor
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.2
 platform: ruby
 authors:
 - Huw Diprose
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-05-29 00:00:00.000000000 Z
-dependencies: []
+date: 2024-01-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: link_header
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.8
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
 description: 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.
@@ -19,15 +131,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".env.example"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/api_adaptor.rb
+- lib/api_adaptor/base.rb
+- lib/api_adaptor/exceptions.rb
+- lib/api_adaptor/headers.rb
+- lib/api_adaptor/json_client.rb
+- lib/api_adaptor/list_response.rb
+- lib/api_adaptor/null_logger.rb
+- lib/api_adaptor/response.rb
+- lib/api_adaptor/variables.rb
 - lib/api_adaptor/version.rb
 - sig/api_adaptor.rbs
 homepage: https://github.com/huwd/api_adaptor