RubyGems - api_wrapper - Versions diffs - 0.1.6 - Mend

api_wrapper 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

checksums.yaml +7 -0
data/.rubocop.yml +7 -0
data/CHANGELOG.md +18 -0
data/CODE_OF_CONDUCT.md +84 -0
data/Gemfile +22 -0
data/LICENSE.txt +21 -0
data/README.md +153 -0
data/Rakefile +31 -0
data/api_wrapper.gemspec +34 -0
data/doc/ApiWrapper/ApiManager.html +807 -0
data/doc/ApiWrapper/Cache/CachePolicy.html +907 -0
data/doc/ApiWrapper/Cache/CacheStore.html +674 -0
data/doc/ApiWrapper/Cache.html +117 -0
data/doc/ApiWrapper/Configuration.html +366 -0
data/doc/ApiWrapper/HttpClient/BaseClient.html +349 -0
data/doc/ApiWrapper/HttpClient/FaradayClient.html +299 -0
data/doc/ApiWrapper/HttpClient.html +117 -0
data/doc/ApiWrapper.html +543 -0
data/doc/_index.html +195 -0
data/doc/class_list.html +54 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +58 -0
data/doc/css/style.css +503 -0
data/doc/file.README.html +248 -0
data/doc/file_list.html +59 -0
data/doc/frames.html +22 -0
data/doc/index.html +248 -0
data/doc/js/app.js +344 -0
data/doc/js/full_list.js +242 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +286 -0
data/doc/top-level-namespace.html +110 -0
data/lib/api_wrapper/api_manager.rb +86 -0
data/lib/api_wrapper/cache/README.md +78 -0
data/lib/api_wrapper/cache/cache_policy.rb +115 -0
data/lib/api_wrapper/cache/cache_store.rb +84 -0
data/lib/api_wrapper/cache/redis_cache_store.rb +3 -0
data/lib/api_wrapper/http_client/base_client.rb +26 -0
data/lib/api_wrapper/http_client/faraday_client.rb +81 -0
data/lib/api_wrapper/version.rb +5 -0
data/lib/api_wrapper.rb +83 -0
metadata +121 -0

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.37
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+<script type="text/javascript">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="ApiWrapper.html" title="ApiWrapper (module)">ApiWrapper</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Mon Sep 16 23:22:30 2024 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.37 (ruby-3.2.2).
+</div>
+    </div>
+  </body>
+</html>

data/lib/api_wrapper/api_manager.rb ADDED Viewed

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+require 'yaml'
+require_relative 'http_client/faraday_client'
+require_relative 'cache/cache_policy'
+require_relative 'cache/cache_store'
+module ApiWrapper
+  # ApiManager is responsible for managing API interactions, including fetching data from endpoints
+  # and handling caching behavior.
+  #
+  # It supports configuration of caching policies, including specifying endpoints that should bypass
+  # the cache and setting custom TTL (time-to-live) values for individual endpoints. The class
+  # uses a Faraday client for making HTTP requests and integrates with a cache store for storing
+  # and retrieving cached data.
+  #
+  # Usage:
+  #   api_manager = ApiWrapper::ApiManager.new('path/to/api_configuration.yml')
+  #
+  #   response = api_manager.fetch_data('endpoint_key')
+  #   puts response.body
+  #
+  # @attr_reader [Hash] endpoints The endpoints configuration loaded from the API configuration file.
+  # @attr_reader [String] base_url The base URL for API requests.
+  # @attr_reader [CachePolicy] cache_policy The cache policy used for caching data.
+  # @attr_reader [FaradayClient] client The Faraday client used for making HTTP requests.
+  class ApiManager
+    # Initializes a new instance of the ApiManager class.
+    #
+    # @param api_configuration_path [String] Path to the API configuration file.
+    # @param cache_store [CacheStore, RedisCacheStore, nil] The cache store to use for caching.
+    # Defaults to in-memory cache if nil.
+    def initialize(api_configuration_path, cache_store: nil)
+      load_api_configuration(api_configuration_path)
+      # Initialize cache policy
+      @cache_policy = ApiWrapper::Cache::CachePolicy.new(cache_store || ApiWrapper::Cache::CacheStore.new)
+      # Configure cache policy
+      configure_cache_policy
+      # Initialize Faraday client
+      @client = ApiWrapper::HttpClient::FaradayClient.new(@base_url, @cache_policy)
+    end
+    # Fetches data from the specified API endpoint.
+    #
+    # @param endpoint_key [String] The key of the API endpoint to fetch data from.
+    # @param force_refresh [Boolean] Whether to force refresh the data, bypassing the cache.
+    # @return [Faraday::Response] The response object containing the fetched data.
+    # @raise [ArgumentError] If the provided endpoint key is invalid.
+    def fetch_data(endpoint_key, force_refresh: false)
+      endpoint = @endpoints[endpoint_key]
+      raise ArgumentError, "Invalid endpoint key: #{endpoint_key}" unless endpoint
+      @cache_policy.fetch(endpoint['path'], force_refresh:) do
+        @client.get(endpoint['path'])
+      end
+    end
+    attr_reader :endpoints, :base_url
+    private
+    # Loads the API configuration from the configuration file.
+    #
+    # @raise [RuntimeError] If the configuration file is missing or has syntax errors.
+    def load_api_configuration(api_configuration_path)
+      yaml_content = YAML.load_file(api_configuration_path)
+      @endpoints = yaml_content['apis']
+      @base_url = yaml_content['base_url']
+    rescue Errno::ENOENT => e
+      raise "Configuration file not found: #{e.message}"
+    rescue Psych::SyntaxError => e
+      raise "YAML syntax error: #{e.message}"
+    end
+    # Configures the cache policy with settings from the configuration file.
+    def configure_cache_policy
+      @endpoints.each_value do |endpoint|
+        @cache_policy.add_no_cache_endpoint(endpoint['path']) if endpoint['no_cache']
+        @cache_policy.add_custom_ttl(endpoint['path'], endpoint['ttl']) if endpoint['ttl']
+      end
+    end
+  end
+end

data/lib/api_wrapper/cache/README.md ADDED Viewed

@@ -0,0 +1,78 @@
+<!-- Note: This readme is simply moved from nse_data, so reflect on this doc for any minor mistakes. -->
+# Caching Mechanism Usage and Customization
+## Overview
+The **ApiWrapper** gem includes a flexible caching mechanism to improve performance and reduce redundant API calls. This documentation provides an overview of how to use and customize the caching mechanism.
+## Cache Policy
+The `CachePolicy` class is responsible for managing caching behavior, including setting global TTLs, custom TTLs for specific endpoints, and controlling which endpoints should bypass the cache.
+### Initializing CachePolicy
+To use caching, you need to initialize the `CachePolicy` with a cache store and optional global TTL:
+```ruby
+require 'api_wrapper/cache/cache_policy'
+require 'api_wrapper/cache/cache_store'
+# Initialize the cache store (e.g., in-memory cache store)
+cache_store = ApiWrapper::Cache::CacheStore.new
+# Initialize the CachePolicy with the cache store and a global TTL of 300 seconds (5 minutes)
+cache_policy = ApiWrapper::Cache::CachePolicy.new(cache_store, global_ttl: 300)
+```
+### Configuring Cache Policy
+#### Adding No-Cache Endpoints
+You can specify endpoints that should bypass the cache:
+```ruby
+# Add an endpoint to the no-cache list
+cache_policy.add_no_cache_endpoint('/no-cache')
+```
+#### Adding Custom TTLs
+You can define custom TTLs for specific endpoints:
+```ruby
+# Set a custom TTL of 600 seconds (10 minutes) for a specific endpoint
+cache_policy.add_custom_ttl('/custom-ttl', ttl: 600)
+```
+#### Fetching Data with Cache
+Use the fetch method to retrieve data with caching applied:
+```ruby
+# Fetch data for an endpoint with optional cache
+data = cache_policy.fetch('/some-endpoint') do
+  # The block should fetch fresh data if cache is not used or is stale
+  # e.g., perform an API call or other data retrieval operation
+  Faraday::Response.new(body: 'fresh data')
+end
+```
+## Custom Cache Stores
+You can extend the caching mechanism to support different types of cache stores. Implement a custom cache store by inheriting from the CacheStore base class and overriding the read and write methods.
+### Example Custom Cache Store
+```ruby
+class CustomCacheStore < ApiWrapper::Cache::CacheStore
+  def read(key)
+    # Implement custom read logic
+  end
+  def write(key, value, ttl)
+    # Implement custom write logic
+  end
+end
+```
+### Using a Custom Cache Store
+To use a custom cache store, initialize CachePolicy with an instance of your custom cache store:
+```ruby
+# Initialize the custom cache store
+custom_cache_store = CustomCacheStore.new
+# Initialize CachePolicy with the custom cache store
+cache_policy = ApiWrapper::Cache::CachePolicy.new(custom_cache_store, global_ttl: 300)
+```

data/lib/api_wrapper/cache/cache_policy.rb ADDED Viewed

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+module ApiWrapper
+  module Cache
+    # CachePolicy manages caching behavior, including cache storage and time-to-live (TTL) settings.
+    #
+    # It allows setting global TTLs, custom TTLs for specific endpoints, and controlling which
+    # endpoints should not use the cache.
+    #
+    # @attr_reader [CacheStore] cache_store The cache store used for storing cached data.
+    class CachePolicy
+      attr_reader :cache_store
+      # Initializes the CachePolicy with a cache store and global TTL.
+      #
+      # @param cache_store [CacheStore, RedisCacheStore] The cache store to use for caching.
+      # @param global_ttl [Integer] The default TTL (in seconds) for caching.
+      def initialize(cache_store, global_ttl = 300)
+        @cache_store = cache_store
+        @global_ttl = global_ttl
+        @custom_ttls = {}
+        @no_cache_endpoints = []
+      end
+      # Adds an endpoint that should bypass the cache.
+      #
+      # @param endpoint [String] The endpoint to exclude from caching.
+      def add_no_cache_endpoint(endpoint)
+        @no_cache_endpoints << endpoint
+      end
+      # Adds a custom TTL for a specific endpoint.
+      #
+      # @param endpoint [String] The endpoint to apply a custom TTL to.
+      # @param ttl [Integer] The custom TTL value in seconds.
+      def add_custom_ttl(endpoint, ttl = 300)
+        @custom_ttls[endpoint] = ttl
+      end
+      # Returns the TTL for a specific endpoint. Defaults to the global TTL if no custom TTL is set.
+      #
+      # @param endpoint [String] The endpoint to fetch the TTL for.
+      # @return [Integer] The TTL in seconds.
+      def ttl_for(endpoint)
+        @custom_ttls.fetch(endpoint, @global_ttl)
+      end
+      # Determines if caching should be used for the given endpoint.
+      #
+      # @param endpoint [String] The endpoint to check.
+      # @return [Boolean] True if caching is enabled for the endpoint, false otherwise.
+      def use_cache?(endpoint)
+        !@no_cache_endpoints.include?(endpoint)
+      end
+      # Fetches the data for the given endpoint, using cache if applicable.
+      #
+      # @param endpoint [String] The endpoint to fetch data for.
+      # @param force_refresh [Boolean] Whether to force refresh the data, bypassing the cache.
+      # @yield The block that fetches fresh data if cache is not used or is stale.
+      # @return [Object] The data fetched from cache or fresh data.
+      def fetch(endpoint, force_refresh: false, &block)
+        if force_refresh || !use_cache?(endpoint)
+          fetch_fresh_data(endpoint, &block)
+        else
+          fetch_cached_or_fresh_data(endpoint, &block)
+        end
+      end
+      private
+      # Fetches fresh data and writes it to the cache if applicable.
+      #
+      # @param endpoint [String] The endpoint to fetch fresh data for.
+      # @yield The block that fetches fresh data.
+      # @return [Object] The fresh data.
+      def fetch_fresh_data(endpoint)
+        fresh_data = yield
+        cache_fresh_data(endpoint, fresh_data)
+        fresh_data
+      end
+      # Fetches cached data or fresh data if not available in the cache.
+      #
+      # @param endpoint [String] The endpoint to fetch data for.
+      # @yield The block that fetches fresh data if cache is not used or is stale.
+      # @return [Object] The cached or fresh data.
+      def fetch_cached_or_fresh_data(endpoint, &block)
+        cached_data = @cache_store.read(endpoint)
+        if cached_data
+          Faraday::Response.new(body: cached_data)
+        else
+          fetch_fresh_data(endpoint, &block)
+        end
+      end
+      # Writes fresh data to the cache.
+      #
+      # @param endpoint [String] The endpoint for which to store the data.
+      # @param fresh_data [Object] The data to be stored in the cache.
+      def cache_fresh_data(endpoint, fresh_data)
+        ttl = determine_ttl(endpoint)
+        @cache_store.write(endpoint, fresh_data.body, ttl) if fresh_data.is_a?(Faraday::Response)
+      end
+      # Determines the TTL value for the given endpoint.
+      #
+      # @param endpoint [String] The endpoint to fetch the TTL for.
+      # @return [Integer] The TTL value in seconds.
+      def determine_ttl(endpoint)
+        @custom_ttls.fetch(endpoint, @global_ttl)
+      end
+    end
+  end
+end

data/lib/api_wrapper/cache/cache_store.rb ADDED Viewed

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+module ApiWrapper
+  module Cache
+    # CacheStore class provides an in-memory caching mechanism.
+    class CacheStore
+      def initialize
+        @store = {}
+      end
+      # Retrieves the cached data for the given key, or fetches fresh data if not cached or expired.
+      #
+      # @param key [String] The cache key.
+      # @param ttl [Integer] The time-to-live in seconds.
+      # @yield Fetches fresh data if cache is expired or not present.
+      # @return [Object] The cached data or the result of the block if not cached or expired.
+      def fetch(key, ttl)
+        if cached?(key, ttl)
+          @store[key][:data]
+        else
+          fresh_data = yield
+          store(key, fresh_data, ttl)
+          fresh_data
+        end
+      end
+      # Reads data from the cache.
+      #
+      # @param key [String] The cache key.
+      # @return [Object, nil] The cached data, or nil if not present.
+      def read(key)
+        cached?(key) ? @store[key][:data] : nil
+      end
+      # Writes data to the cache with an expiration time.
+      #
+      # @param key [String] The cache key.
+      # @param data [Object] The data to cache.
+      # @param ttl [Integer] The time-to-live in seconds.
+      def write(key, data, ttl)
+        store(key, data, ttl)
+      end
+      # Deletes data from the cache.
+      #
+      # @param key [String] The cache key.
+      def delete(key)
+        @store.delete(key)
+      end
+      private
+      # Checks if the data for the given key is cached and not expired.
+      #
+      # @param key [String] The cache key.
+      # @param ttl [Integer] The time-to-live in seconds.
+      # @return [Boolean] Whether the data is cached and valid.
+      def cached?(key, ttl = nil)
+        return false unless @store.key?(key)
+        !expired?(key, ttl)
+      end
+      # Checks if the cached data for the given key has expired.
+      #
+      # @param key [String] The cache key.
+      # @param ttl [Integer] The time-to-live in seconds.
+      # @return [Boolean] Whether the cached data has expired.
+      def expired?(key, ttl)
+        stored_time = @store[key][:timestamp]
+        ttl && (Time.now - stored_time) >= ttl
+      end
+      # Stores the data in the cache.
+      #
+      # @param key [String] The cache key.
+      # @param data [Object] The data to cache.
+      # @param ttl [Integer] The time-to-live in seconds.
+      def store(key, data, ttl)
+        @store[key] = { data:, timestamp: Time.now, ttl: }
+      end
+    end
+  end
+end

data/lib/api_wrapper/cache/redis_cache_store.rb ADDED Viewed

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+# TODO: Implement in near future :)

data/lib/api_wrapper/http_client/base_client.rb ADDED Viewed

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+module ApiWrapper
+  module HttpClient
+    # Base class for HTTP clients
+    class BaseClient
+      # Initializes a new instance of the BaseClient class.
+      #
+      # @param base_url [String] The base URL for the HTTP client.
+      def initialize(base_url, cache_policy)
+        @base_url = base_url
+        @cache_policy = cache_policy
+      end
+      # Sends a GET request to the specified endpoint.
+      #
+      # @param endpoint [String] The endpoint to send the GET request to.
+      # @raise [NotImplementedError] If the method is not implemented by subclasses.
+      def get(endpoint)
+        raise NotImplementedError, 'Subclasses must implement the get method'
+      end
+      # TODO: Other HTTP methods like post, put, delete can be added here if needed
+    end
+  end
+end

data/lib/api_wrapper/http_client/faraday_client.rb ADDED Viewed

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+require 'faraday'
+require 'faraday-http-cache'
+require 'json'
+require_relative 'base_client'
+module ApiWrapper
+  module HttpClient
+    # FaradayClient class is responsible for making HTTP requests using Faraday.
+    class FaradayClient < BaseClient
+      # Sends a GET request to the specified endpoint.
+      #
+      # @param endpoint [String] The endpoint to send the request to.
+      # @param force_refresh [Boolean] Whether to force a cache refresh.
+      # @return [Faraday::Response] The response object.
+      def get(endpoint, force_refresh: false)
+        # Use the cache policy to determine whether to fetch from cache or refresh.
+        @cache_policy.fetch(endpoint, force_refresh:) do
+          handle_connection(endpoint) do |connection|
+            connection.get(endpoint)
+          end
+        end
+      end
+      private
+      # Handles the connection to the base URL.
+      #
+      # @yield [connection] The Faraday connection object.
+      # @yieldparam connection [Faraday::Connection] The Faraday connection object.
+      # @return [Object] The result of the block execution.
+      # @raise [Faraday::Error] If there is an error with the connection.
+      def handle_connection(endpoint)
+        connection = build_faraday_connection(endpoint)
+        yield(connection)
+      rescue Faraday::Error => e
+        handle_faraday_error(e)
+      end
+      # Builds the Faraday connection with proper configuration.
+      #
+      # @param endpoint [String] The endpoint for the connection.
+      # @return [Faraday::Connection] The configured Faraday connection.
+      def build_faraday_connection(endpoint)
+        Faraday.new(url: @base_url) do |faraday|
+          configure_faraday(faraday)
+          apply_cache_policy(faraday, endpoint) if @cache_policy.use_cache?(endpoint)
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+      # Configures Faraday with default headers and request options.
+      #
+      # @param faraday [Faraday::Connection] The Faraday connection object.
+      def configure_faraday(faraday)
+        faraday.request :json
+        faraday.headers['User-Agent'] = 'ApiWrapperClient/1.0'
+        faraday.response :json
+        faraday.headers['Accept'] = 'application/json'
+      end
+      # Applies the cache policy to the Faraday connection if caching is enabled.
+      #
+      # @param faraday [Faraday::Connection] The Faraday connection object.
+      # @param endpoint [String] The endpoint to be cached.
+      def apply_cache_policy(faraday, endpoint)
+        ttl = @cache_policy.ttl_for(endpoint)
+        faraday.use :http_cache, store: @cache_policy.cache_store, expire_after: ttl
+      end
+      # Handles any Faraday errors.
+      #
+      # @param error [Faraday::Error] The error raised by Faraday.
+      # @raise [StandardError] Raises the original error with full context.
+      def handle_faraday_error(error)
+        raise StandardError, "Faraday error: #{error.message}"
+      end
+    end
+  end
+end

data/lib/api_wrapper/version.rb ADDED Viewed

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module ApiWrapper
+  VERSION = '0.1.6'
+end

data/lib/api_wrapper.rb ADDED Viewed

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+require_relative 'api_wrapper/version'
+require_relative 'api_wrapper/api_manager'
+# ApiWrapper provides a unified interface for managing API interactions and caching.
+#
+# It simplifies API management and caching with sensible defaults and customization options.
+#
+# Usage:
+#   # Fetch data using default configuration
+#   response = ApiWrapper.fetch_data('endpoint_key')
+#   puts response.body
+#
+#   # Configure with custom settings
+#   ApiWrapper.configure do |config|
+#     config.api_configuration_path = 'custom/path/to/config.yml'
+#     config.cache_store = CustomCacheStore.new
+#   end
+#   response = ApiWrapper.fetch_data('endpoint_key')
+#   puts response.body
+module ApiWrapper
+  # Configuration class for managing settings
+  class Configuration
+    attr_accessor :api_configuration_path, :cache_store
+    def initialize
+      @api_configuration_path = default_api_configuration_path
+      @cache_store = default_cache_store
+    end
+    private
+    # Default API configuration path
+    def default_api_configuration_path
+      ENV['API_CONFIGURATION_PATH'] || File.join(Dir.pwd, 'config', 'api_endpoints.yml')
+    end
+    # Default cache store
+    def default_cache_store
+      cache_type = ENV['CACHE_STORE_TYPE'] || 'in_memory'
+      case cache_type
+      when 'redis'
+        ApiWrapper::Cache::RedisCacheStore.new # TODO: implement RedisCacheStore later
+      else
+        ApiWrapper::Cache::CacheStore.new
+      end
+    end
+  end
+  class << self
+    # Accesses the configuration instance, initializing if needed
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    # Configures ApiWrapper with a block
+    def configure
+      raise ArgumentError, 'Configuration block required' unless block_given?
+      yield(configuration)
+      reset_api_manager!
+    end
+    # Returns the singleton ApiManager instance
+    def api_manager
+      @api_manager ||= begin
+        config = configuration
+        ApiManager.new(config.api_configuration_path, cache_store: config.cache_store)
+      end
+    end
+    # Fetches data from the specified endpoint
+    def fetch_data(endpoint_key, force_refresh: false)
+      api_manager.fetch_data(endpoint_key, force_refresh:)
+    end
+    # Resets the ApiManager instance
+    def reset_api_manager!
+      @api_manager = nil
+    end
+  end
+end