feat: implement new register.fetch interface

Author: ronaldtse

.rubocop_todo.yml

@@ -1,12 +1,19 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-03-10 09:19:41 UTC using RuboCop version 1.73.2.
+# on 2025-03-10 11:29:40 UTC using RuboCop version 1.73.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 2
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect.
+Lint/UselessAssignment:
+  Exclude:
+    - 'spec/lutaml/hal/page_spec.rb'
+
+# Offense count: 3
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
   Max: 28
@@ -15,9 +22,9 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 174
+  Max: 177
 
-# Offense count: 6
+# Offense count: 8
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 21
@@ -43,7 +50,7 @@ Naming/HeredocDelimiterNaming:
   Exclude:
     - 'spec/lutaml/hal/integration_spec.rb'
 
-# Offense count: 9
+# Offense count: 6
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64

README.adoc

@@ -56,20 +56,82 @@ Or install it yourself as:
 $ gem install lutaml-hal
 ----
 
+== Structure
+
+The classes in this library are organized into the following modules:
+
+`Lutaml::Hal::Client`::
+A client for making HTTP requests to HAL APIs. It includes methods for setting
+the API endpoint, making GET requests, and handling responses.
++
+NOTE: Only GET requests are supported at the moment.
+
+`Lutaml::Hal::ModelRegister`::
+A registry for managing HAL resource models and their endpoints. It allows you
+to register models, define their relationships, and fetch resources from the
+API.
+
+`Lutaml::Hal::Resource`::
+A base class for defining HAL resource models. It includes methods for
+defining attributes, links, and key-value mappings for resources.
+
+`Lutaml::Hal::Link`::
+A class for defining HAL links. It includes methods for specifying the
+relationship between resources and their links, as well as methods for
+resolving links to their target resources.
+
+`Lutaml::Hal::Page`::
+A class for handling pagination in HAL APIs. It includes methods for
+defining pagination attributes, such as `page`, `pages`, `limit`, and
+`total`, as well as methods for accessing linked resources within a page.
+
+
 == Usage
 
-=== Creating a Client
+=== General
+
+In order to interact with a HAL API, the following steps are required:
+
+. Create a `Client` that points to the API endpoint.
+. Create a `ModelRegister` to manage the resource models and their
+respective endpoints.
+. Define the resource models using the `Resource` class.
+. Register the models with the `ModelRegister`.
+. Fetch resources from the API using the `ModelRegister`.
+.. Once the resources are fetched, you can access their attributes and links
+and navigate through the resource graph.
+. Pagination, such as on "index" type pages, can be handled by subclassing the `Page` class.
+The `Page` class itself is also implemented as a `Resource`, so you can
+use the same methods to access the page's attributes and links.
+
+
+=== Creating a HAL model register
 
 [source,ruby]
 ----
 require 'lutaml-hal'
 
 # Create a new client with API endpoint
-client = Lutaml::Hal::Client.new(api_endpoint: 'https://api.example.com')
-register = Lutaml::Hal::ModelRegister.new
-register.client = client
+client = Lutaml::Hal::Client.new(api_url: 'https://api.example.com')
+register = Lutaml::Hal::ModelRegister.new(client: client)
+# Or set client later, `register.client = client`
+
+register.add_endpoint(
+  id: :product_index,
+  type: :index,
+  url: '/products',
+  model: Product
+)
+register.add_endpoint(
+  id: :product_resource,
+  type: :resource,
+  url: '/products/{id}',
+  model: Product
+)
+
+register.fetch(:product_index)
+# => client.get('/products')
 
-client.get('/products')
 # => {
 # "page": 1,
 # "pages": 10,
@@ -84,9 +146,35 @@ client.get('/products')
 #     { "id": 2, "name": "Product 2", "price": 15.0 }
 #   ]
 # }
+
+product_1 = register.fetch(:product_resource, id: 1)
+# => client.get('/products/1')
+
+# => {
+# "id": 1,
+# "name": "Product 1",
+# "price": 10.0,
+# "_links": {
+#   "self": { "href": "/products/1" },
+#   "category": { "href": "/categories/1", "title": "Category 1" },
+#   "related": [
+#      { "href": "/products/3", "title": "Product 3" },
+#      { "href": "/products/5", "title": "Product 5" }
+#   ]
+# }
+# }
+
+product_1
+# => #<Product id: 1, name: "Product 1", price: 10.0, links:
+#      #<ProductLinks self: <ProductLink href: "/products/1">,
+#                     category: <ProductLink href: "/categories/1", title: "Category 1">,
+#                     related: [
+#                         <ProductLink href: "/products/3", title: "Product 3">,
+#                         <ProductLink href: "/products/5", title: "Product 5">
+#                     ]}>
 ----
 
-=== Defining Resources
+=== Defining resource models
 
 [source,ruby]
 ----
@@ -111,6 +199,8 @@ module MyApi
 end
 ----
 
+=== Registering endpoints
+
 === Fetching Resources
 
 [source,ruby]

lib/lutaml/hal/client.rb

@@ -10,10 +10,10 @@ module Lutaml
   module Hal
     # HAL Client for making HTTP requests to HAL APIs
     class Client
-      attr_reader :last_response, :api_endpoint, :connection
+      attr_reader :last_response, :api_url, :connection
 
       def initialize(options = {})
-        @api_endpoint = options[:api_endpoint] || raise(ArgumentError, 'api_endpoint is required')
+        @api_url = options[:api_url] || raise(ArgumentError, 'api_url is required')
         @connection = options[:connection] || create_connection
         @params_default = options[:params_default] || {}
         @debug = options[:debug] || !ENV['DEBUG_API'].nil?
@@ -24,7 +24,7 @@ def initialize(options = {})
       # Get a resource by its full URL
       def get_by_url(url, params = {})
         # Strip API endpoint if it's included
-        path = url.sub(%r{^#{@api_endpoint}/}, '')
+        path = url.sub(%r{^#{@api_url}/}, '')
         get(path, params)
       end
 
@@ -53,7 +53,7 @@ def get(url, params = {})
       private
 
       def create_connection
-        Faraday.new(url: @api_endpoint) do |conn|
+        Faraday.new(url: @api_url) do |conn|
           conn.use Faraday::FollowRedirects::Middleware
           conn.request :json
           conn.response :json, content_type: /\bjson$/

lib/lutaml/hal/model_register.rb

@@ -8,21 +8,51 @@ module Hal
     class ModelRegister
       attr_accessor :models, :client
 
+      def initialize(client: nil)
+        # If `client` is not set, it can be set later
+        @client = client
+        @models = {}
+      end
+
       # Register a model with its base URL pattern
-      def register(model_class, url_pattern)
+      def add_endpoint(id:, type:, url:, model:)
         @models ||= {}
-        @models[url_pattern] = model_class
+
+        raise "Model with ID #{id} already registered" if @models[id]
+        if @models.values.any? { |m| m[:url] == url && m[:type] == type }
+          raise "Duplicate URL pattern #{url} for type #{type}"
+        end
+
+        @models[id] = {
+          id: id,
+          type: type,
+          url: url,
+          model: model
+        }
       end
 
       # Resolve and cast data to the appropriate model based on URL
+      def fetch(endpoint_id, **params)
+        endpoint = @models[endpoint_id] || raise("Unknown endpoint: #{endpoint_id}")
+        raise 'Client not configured' unless client
+
+        url = interpolate_url(endpoint[:url], params)
+        response = client.get(url)
+
+        endpoint[:model].from_json(response.to_json)
+      end
+
       def resolve_and_cast(href)
         raise 'Client not configured' unless client
 
         debug_log("href #{href}")
         response = client.get_by_url(href)
+
+        # TODO: Merge more content into the resource
         response_with_link_details = response.to_h.merge({ 'href' => href })
 
-        model_class = find_matching_model_class(href)
+        href_path = href.sub(client.api_url, '')
+        model_class = find_matching_model_class(href_path)
         raise LinkResolutionError, "Unregistered URL pattern: #{href}" unless model_class
 
         debug_log("model_class #{model_class}")
@@ -34,37 +64,45 @@ def resolve_and_cast(href)
 
       private
 
+      def interpolate_url(url_template, params)
+        params.reduce(url_template) do |url, (key, value)|
+          url.gsub("{#{key}}", value.to_s)
+        end
+      end
+
       def find_matching_model_class(href)
-        @models.find do |pattern, _|
-          debug_log("pattern #{pattern}")
-          matches_url?(pattern, href)
-        end&.last
+        @models.values.find do |model_data|
+          matches_url?(model_data[:url], href)
+        end&.[](:model)
       end
 
       def matches_url?(pattern, href)
         return false unless pattern && href
 
-        if href.start_with?('/') && client&.api_endpoint
+        if href.start_with?('/') && client&.api_url
           # Try both with and without the API endpoint prefix
           path_pattern = extract_path(pattern)
           return pattern_match?(path_pattern, href) ||
-                 pattern_match?(pattern, "#{client.api_endpoint}#{href}")
+                 pattern_match?(pattern, "#{client.api_url}#{href}")
         end
 
         pattern_match?(pattern, href)
       end
 
       def extract_path(pattern)
-        return pattern unless client&.api_endpoint && pattern.start_with?(client.api_endpoint)
+        return pattern unless client&.api_url && pattern.start_with?(client.api_url)
 
-        pattern.sub(client.api_endpoint, '')
+        pattern.sub(client.api_url, '')
       end
 
-      # Match URL pattern (supports * wildcards)
+      # Match URL pattern (supports * wildcards and {param} templates)
       def pattern_match?(pattern, url)
         return false unless pattern && url
 
-        regex = Regexp.new("^#{pattern.gsub('*', '.*')}$")
+        # Convert {param} to wildcards for matching
+        pattern_with_wildcards = pattern.gsub(/\{[^}]+\}/, '*')
+        # Convert * wildcards to regex pattern
+        regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
         regex.match?(url)
       end