RubyGems - api_wrapper - Versions diffs - 0.1.6 - Mend

api_wrapper 0.1.6

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