lutaml-hal 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea54d1764e2083f8ba5e232022fa2bae95db1775db65e1be46101c3dc2db3a8
-  data.tar.gz: 3d519340919d3f8d84b5c6a38bc73796fbf662cc40c4a01cc030b3cfad9b00ea
+  metadata.gz: e5a918f01a4197929abfdbbdd1e061ecff5d37592ed0c880024ec11f6abe2943
+  data.tar.gz: 032f6ba78ced7adefc4b6a9ce9c2c76acc25eba6b9d3d96398f3f09d330d312b
 SHA512:
-  metadata.gz: 31543a34726a0d12557f07aae9d9f70fba8ea936abb0b3f8792d26741ba4f353fcd7b9fd08e2cbff44e91819e18efcb5b67a3c50714752221c58f6a39c7761f1
-  data.tar.gz: 2422ddeeb2903e7adce861fce307594c11f5d147b185121e082ad49fe19156016a940ee9199d6591ab203942c4713e48c0ab3d375bf03d944df5faa914a1b4b1
+  metadata.gz: '0802c9c05fbb34fc5a8d53a023cdd1cfda2291305b597387a5cc7afc665c9aa7eac542f03840cac494389c49442a030e79e7fdcf2169d992747e7a707fc4d9fa'
+  data.tar.gz: 7ecabcdc778455d9d4fee7b9708c7754891ab64e3da5edb6b88927cc687806b3c5863dde63b89aa785cdcf8174c431b58fa862e0a6443e456faad13fcced0faf

data/README.adoc

@@ -86,27 +86,59 @@ defining pagination attributes, such as `page`, `pages`, `limit`, and
 `total`, as well as methods for accessing linked resources within a page.
 
 
-== Usage
+== Usage overview
 
-=== General
+In order to interact with a HAL API using `lutaml-hal`, there are two
+stages of usage: data definition and runtime.
 
-In order to interact with a HAL API, the following steps are required:
+At the data definition phase:
 
-. Create a `Client` that points to the API endpoint.
+. Define the API endpoint using the `Client` class.
 . 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`.
+. Register the models with the `ModelRegister` and define their
+relationships using the `add_endpoint` method.
+
+Once data definition is present, the following operations can be performed at
+runtime:
+
+. Fetch resources from the API using the `ModelRegister` and `Link#realize` methods.
+
 .. 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
++
+NOTE: 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.
 
 
+== Usage: Data definition
+
+=== General
+
+HAL resources need to be defined as models to allow data access and serialization.
+
+The following steps are required:
+
+. Define HAL resource models.
+. Define the base API URL using the `Client` class.
+. Create a `ModelRegister` to manage the resource models.
+. Define the resource models' respective endpoints on the base API URL.
+
+
 === Creating a HAL model register
 
+The `ModelRegister` class is used to manage the resource models and their
+respective endpoints on the base API URL.
+
+It relies on the `Client` class to perform HTTP requests to the API. The base
+API URL is defined at the `Client` object.
+
+NOTE: The base API URL is used for all requests made by the `Client` class,
+including the requests made by the `ModelRegister` class.
+
 [source,ruby]
 ----
 require 'lutaml-hal'
@@ -115,53 +147,499 @@ require 'lutaml-hal'
 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`
+----
+
+
+=== Defining HAL resource models
+
+==== General
+
+A HAL resource is defined by creating a subclass of the `Resource` class and
+defining its attributes, links, and key-value mappings.
+
+The `Resource` class is the base class for defining HAL resource models.
+It inherits from `Lutaml::Model::Serialization`, which provides data
+modelling and serialization capabilities.
+
+The declaration of attributes, links, and key-value mappings for a HAL resource
+is performed using the `attribute`, `hal_link`, and `key_value` methods.
+
+There are 3 levels of data modeling in a HAL resource, all of which are necessary
+for the full usage of a HAL resource:
+
+* Resource attributes
+* Serialization mappings
+* HAL Links
+
+
+.Integrated example of a resource model
+[example]
+====
+[source,ruby]
+----
+module MyApi
+  class Product < Lutaml::Hal::Resource
+    attribute :id, :string
+    attribute :name, :string
+    attribute :price, :float
+
+    hal_link :self, key: 'self', realize_class: 'Product'
+    hal_link :category, key: 'category', realize_class: 'Category'
+
+    key_value do
+      map 'id', to: :id
+      map 'name', to: :name
+      map 'price', to: :price
+    end
+  end
+end
+----
+====
+
+
+==== Resource attributes
+
+A resource attribute is a direct property of the HAL resource.
+
+These attributes typically hold values of simple data types, and are directly
+serialized into JSON.
+
+These attributes are declared using the `attribute` method from `lutaml-model`.
+
+[example]
+====
+A HAL resource of class `Product` can have attributes `id`, `name`, and `price`.
+====
+
+Please refer to syntax as described in the
+https://github.com/lutaml/lutaml-model[`lutaml-model`] documentation.
+
+.Example of a resource model with attributes
+[example]
+====
+[source,ruby]
+----
+module MyApi
+  class Product < Lutaml::Hal::Resource
+    attribute :id, :string
+    attribute :name, :string
+    attribute :price, :float
+    # ...
+  end
+end
+----
+====
+
+==== Serialization mapping of resource attributes
+
+A serialization mapping defines rules to serialize a HAL resource to and from a
+serialization format. In HAL, the serialization format is JSON, but other formats
+can also be supported.
+
+The mapping between the HAL model attributes and their corresponding JSON
+serialization is performed using the `key_value do` or `json do` blocks from
+`lutaml-model`. The mapping of the contents of `_links` is automatically
+performed using `hal_link`.
+
+[example]
+====
+A HAL resource of class `Product` with attributes `id`, `name`, and `price` will
+need to declare a `key_value` block to map the attributes to their corresponding
+JSON keys, namely, `"id"`, `"name"`, and `"price"`.
+====
+
+Please refer to syntax as described in the
+https://github.com/lutaml/lutaml-model[`lutaml-model`] documentation.
+
+.Example of a resource model with serialization mapping
+[example]
+====
+[source,ruby]
+----
+module MyApi
+  class Product < Lutaml::Hal::Resource
+    attribute :id, :string
+    attribute :name, :string
+    attribute :price, :float
+
+    key_value do
+      map 'id', to: :id
+      map 'name', to: :name
+      map 'price', to: :price
+    end
+  end
+end
+----
+====
+
+
+
+==== HAL Links
+
+A HAL resource has links to other resources, typically serialized in
+the `_links` section of the JSON response.
+
+[example]
+====
+A HAL resource of class `Product` can have links `self` (which is a
+self-referential identifier link) and `category`.
+====
+
+HAL links need to be defined in the resource model to allow the resolution of
+the links to their target resources.
+
+These links are declared using the `hal_link` method provided by `lutaml-hal`.
+
+Syntax:
+
+[source,ruby]
+----
+hal_link :link_name,
+  key: 'link_key',
+  realize_class: 'TargetResourceClass',
+  link_class: 'LinkClass',
+  link_set_class: 'LinkSetClass'
+----
+
+`:link_name`:: The name of the link, which will be used to access the link in
+the resource object.
+
+`key: 'link_key'`:: The key of the link in the JSON response. This is the name
+of the link as it appears in the `_links` section of the HAL resource.
+
+`realize_class: 'TargetResourceClass'`:: The class of the target resource that
+the link points to. This is used to resolve the link to the associated resource.
+
+`link_class: 'LinkClass'`:: (optional) The class of the link that defines
+specific behavior or attributes for the link object itself. This is dynamically
+created and is inherited from `Lutaml::Hal::Link` if not provided.
+
+`link_set_class: 'LinkSetClass'`:: (optional) The class of the link set object
+that contains the links. This is dynamically created and is inherited from
+`Lutaml::Model::Serializable` if not provided.
+
+
+The `_links` section is modeled as a dynamically created link set class, named
+after the resource's class name (with an appended `LinkSet` string), which in turn
+contains the defined links to other resources. The link set class is inherited
+from `Lutaml::Model::Serializable`.
+
+[example]
+====
+A HAL resource of class `Product` may have a link set of class `ProductLinkSet`
+which contains the `self` and `category` links as its attributes.
+====
+
+
+Each link object of the link set is provided as a `Link` object that is
+dynamically created for the type of resolved resource. The name of the link
+class is the same as the resource class name with an appended `Link` string.
+This Link class is inherited from `Lutaml::Hal::Link`.
+
+[example]
+====
+A HAL resource of class `Product` with a link set that contains the `self`
+(points to a `Product`) and `category` (points to a `Category`) links will
+have:
+
+* a link set of class `ProductLinks` which contains:
+** a `self` attribute that is an instance of `ProductLink`
+** a `category` attribute that is an instance of `CategoryLink`
+====
+
+
+.Integrated example of a HAL resource model using auto-generated LinkSet and Link classes
+[example]
+====
+For an instance of `Product`:
+
+[source,ruby]
+----
+module MyApi
+  class Product < Lutaml::Hal::Resource
+    attribute :id, :string
+    attribute :name, :string
+    attribute :price, :float
+
+    hal_link :self, key: 'self', realize_class: 'Product'
+    hal_link :category, key: 'category', realize_class: 'Category'
+
+    key_value do
+      map 'id', to: :id
+      map 'name', to: :name
+      map 'price', to: :price
+    end
+  end
+end
+----
+
+The library will provide:
+
+* the link set (serialized in HAL as JSON `_links`) in the class `ProductLinks`.
+
+* the link set contains the `self` and the `category` links of class `Lutaml::Hal::Link`.
+
+As a result:
+
+* calling `product.links.self` will return an instance of `ProductLink`.
+
+* calling `product.links.self.realize(register)` will dynamically fetch and
+return an instance of `Product`.
+====
+
+
+
+==== Custom link set class
+
+When a custom link set class (via `link_set_class:`) is provided, links are no
+longer automatically added to the link set via `hal_link`. Please ensure that
+all links are defined as model `attributes` and their `key_value` mappings
+provided.
+
+This is useful for the scenario where the link set needs to be
+customized to provide additional attributes or behavior.
+
+A LinkSetClass for a resource must implement the following interface:
+
+[source,ruby]
+----
+module MyApi
+  # This represents the link set of a Resource
+  class ResourceLinkSet < Lutaml::Model::Serializable
+    attribute :attribute_name_1, :link_class_1, collection: {true|false}
+    attribute :attribute_name_2, :link_class_2, collection: {true|false}
+    # ...
+
+    key_value do
+      map 'link_key_1', to: :attribute_name_1
+      map 'link_key_2', to: :attribute_name_2
+      # ...
+    end
+  end
+
+  # This represents the basic setup of a Resource with a custom LinkSet class
+  class Resource < Lutaml::Hal::Resource
+    attribute :links, ResourceLinkSet
+    # Define resource attributes
+
+    key_value do
+      # This is the mapping of the `_links` key to the attribute `links`.
+      map '_links', to: :links
+      # Mappings for resource attributes need to be explicitly provided
+    end
+  end
+end
+----
+
+Alternatively, it is possible to re-open the dynamically created link set class
+and add additional attributes to it.
+
+.Override the default link set class for Product
+[source,ruby]
+----
+module MyApi
+  class Product < Lutaml::Hal::Resource
+    attribute :id, :string
+  end
+  # The class `MyApi::ProductLinkSet` is created automatically by the library.
+
+  # Re-open the default link set class and add additional attributes
+  class ProductLinkSet < Lutaml::Hal::LinkSet
+    # Add additional attributes to the link set
+    attribute :custom_link_set_attribute, Something, collection: false
+
+    key_value do
+      map 'my_custom_link', to: :custom_link_set_attribute
+    end
+  end
+end
+----
+
+==== Custom link class
+
+When a custom link class (via `link_class:`) is provided, the custom link class
+is automatically added into the link set.
+
+This makes it possible to:
+
+* supplement the link with additional attributes, or
+* override the `realize(register)` method to provide custom behavior for the link.
+
+A Link class pointing to a resource must implement the following interface:
+
+[source,ruby]
+----
+module MyApi
+  # This represents a link set pointing to a Resource
+  class TargetResourceLink < Lutaml::Model::Serializable
+    # This is the link class for the resource class Resource
+    # 'default:' needs to be set to the name of the target resource class
+    attribute :type, :string, default: 'Resource'
+
+    # No specification of key_value block needed since attribute presence
+    # provides a default mapping.
+  end
+end
+----
+
+Alternatively, it is possible to re-open the dynamically created link class and add
+additional attributes to it.
+
+.Override the default link class for Product
+[source,ruby]
+----
+module MyApi
+  class Product < Lutaml::Hal::Resource
+    attribute :id, :string
+    hal_link :category, key: 'category', realize_class: 'Category'
+  end
+  # The class `MyApi::CategoryLink` is created automatically by the library.
+
+  # Re-open the default link class and add additional attributes
+  class CategoryLink < Lutaml::Hal::Link
+    # Add additional attributes to the link
+    attribute :language_code, :string, collection: false
+
+    key_value do
+      map 'language_code', to: :language_code
+    end
+  end
+end
+----
+
+
+
+=== Registering resource models and endpoints
+
+The `ModelRegister` allows you to register resource models and their endpoints.
+
+You can define endpoints for collections (index) and individual resources
+(resource) using the `add_endpoint` method.
+
+The `add_endpoint` method takes the following parameters:
+
+`id`:: A unique identifier for the endpoint.
+`type`:: The type of endpoint, which can be `index` or `resource`.
+`url`:: The URL of the endpoint, which can include path parameters.
+`model`:: The class of the resource that will be fetched from the API.
+The class must inherit from `Lutaml::Hal::Resource`.
+
+In the `url`, you can use interpolation parameters, which will be replaced with
+the actual values when fetching the resource. The interpolation parameters are
+defined in the `url` string using curly braces `{}`.
+
+The `add_endpoint` method will automatically handle the URL resolution and fetch
+the resource from the API.
+
+When the `ModelRegister` fetches a resource using the `realize` method, it will
+match the resource URL against registered paths in order to find the
+appropriate model class to use for deserialization and resolution.
 
+Syntax:
+
+[source,ruby]
+----
+register.add_endpoint( <1>
+  id: :model_index, <2>
+  type: :index, <3>
+  url: '/url_supporting_interpolation/{param}', <4>
+  model: ModelClass <5>
+)
+----
+<1> The `add_endpoint` method is used to register an endpoint for a model.
+<2> The `id` is a unique identifier for the endpoint, which is required to
+    fetch the resource later.
+<3> The `type` specifies the type of endpoint, which can be `index` or
+    `resource`. The `index` type is used for collections, while the
+    `resource` type is used for individual resources.
+<4> The `url` is the URL of the endpoint, which can include path
+    parameters. The URL can also include interpolation parameters, which
+    will be replaced with the actual values when fetching the resource.
+<5> The `model` is the class of the resource that will be fetched from
+    the API. The class must inherit from `Lutaml::Hal::Resource`.
+
+.Example of registering the Product class to both index and resource endpoints
+[example]
+====
+[source,ruby]
+----
 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')
 
-# => {
-# "page": 1,
-# "pages": 10,
-# "limit": 10,
-# "total": 45,
-# "_links": {
-#   "self": { "href": "/products/1" },
-#   "next": { "href": "/products/2" },
-#   "last": { "href": "/products/5" },
-#   "products": [
-#     { "id": 1, "name": "Product 1", "price": 10.0 },
-#     { "id": 2, "name": "Product 2", "price": 15.0 }
-#   ]
-# }
+== Usage: Runtime
+
+=== General
+
+NOTE: The `lutaml-hal` library currently only supports synchronous data fetching.
+Asynchronous data fetching will be supported in the future.
+
+NOTE: The `lutaml-hal` library currently only supports data fetching requests
+(GET) today. Additional features may be provided in the future.
+
+Once the data definition is complete, you can use the `ModelRegister` to
+fetch and interact with resources from the API.
+
+=== Fetching a resource
+
+The `ModelRegister` allows you to fetch resources from the API using the `fetch`
+method.
+
+NOTE: The endpoint of the resource must be already defined through the
+`add_endpoint` method.
+
+The `fetch` method will automatically handle the URL resolution and fetch the
+resource from the API.
+
+Syntax:
 
+[source,ruby]
+----
+register.fetch(:resource_endpoint_id, {parameters})
+----
+
+Where,
+
+`resource_endpoint_id`:: The ID of the endpoint registered in the
+`ModelRegister`.
+`parameters`:: A hash of parameters to be passed to the API. The parameters
+are used to replace the interpolation parameters in the URL.
+`register`:: The instance of `ModelRegister`.
+
+
+.Fetch a resource directly from the API
+[example]
+====
+[source,ruby]
+----
 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" }
-#   ]
-# }
+#   "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
@@ -173,67 +651,242 @@ product_1
 #                         <ProductLink href: "/products/5", title: "Product 5">
 #                     ]}>
 ----
+====
+
+
+
+=== Fetching a resource index
+
+In HAL, collections are provided via the `_links` or the `_embedded` sections of
+the response.
+
+NOTE: The `_embedded` section is not yet supported by the `Lutaml::Hal` library.
+
+The `ModelRegister` allows you to define endpoints for collections and fetch
+them using the `fetch` method.
+
+The `fetch` method will automatically handle the URL resolution and fetch the
+resource index from the API.
+
+// The `Page` class is used to handle pagination and resource
+// resolution for collections.
 
-=== Defining resource models
+Syntax:
 
 [source,ruby]
 ----
-module MyApi
-  class Product < Lutaml::Hal::Resource
-    attribute :id, :string
-    attribute :name, :string
-    attribute :price, :float
+register.fetch(:index_endpoint_id)
+----
 
-    hal_link :self, key: 'self', realize_class: 'Product'
-    hal_link :category, key: 'category', realize_class: 'Category'
+Where,
 
-    key_value do
-      map 'id', to: :id
-      map 'name', to: :name
-      map 'price', to: :price
-    end
-  end
+`index_endpoint_id`:: The ID of the endpoint registered in the `ModelRegister`.
+`register`:: The instance of `ModelRegister`.
 
-  # Register the model with the registry
-  Lutaml::Hal::ModelRegister.register(Product, '/products/{id}')
-end
+
+.Fetch a collection of resources from the API
+[example]
+====
+[source,ruby]
+----
+product_index = register.fetch(:product_index)
+# => client.get('/products')
+
+# => {
+# "page": 1,
+# "pages": 10,
+# "limit": 10,
+# "total": 45,
+# "_links": {
+#   "self": { "href": "/products/1" },
+#   "next": { "href": "/products/2" },
+#   "last": { "href": "/products/5" },
+#   "products": [
+#     { "href": "/products/1", "title": "Product 1" },
+#     { "href": "/products/2", "title": "Product 2" }
+#   ]
+# }
+
+product_index
+# => #<ProductPage page: 1, pages: 10, limit: 10, total: 45,
+#      links: #<ProductLinks self: <ProductLink href: "/products/1">,
+#                     next: <ProductLink href: "/products/2">,
+#                     last: <ProductLink href: "/products/5">,
+#                     products: <ProductLinks
+#                         <ProductLink href: "/products/1", title: "Product 1">,
+#                         <ProductLink href: "/products/2", title: "Product 2">
+#                     ]>>
 ----
+====
+
 
-=== Registering endpoints
+=== Fetching a resource via link realization
 
-=== Fetching Resources
+Given a resource index that contains links to resources, the individual resource
+links can be "realized" as actual model instances through the
+`Link#realize(register)` method which dynamically retrieves the resource.
+
+Given a `Link` object, the `realize` method fetches the resource from the API
+using the provided `register`.
+
+Syntax:
 
 [source,ruby]
 ----
-# Assume that the client is already created and registered at
-# the ModelRegister
-# Get a resource
-product = client.get('products/123')
-product_resource = MyApi::Product.from_json(product.to_json)
+Lutaml::Model::Link.new(
+  href: 'resource_endpoint_href',
+  # ... other attributes
+).realize(register)
+----
 
-# Follow a link
-category = product_resource.category.realize(register)
+Where,
+
+`resource_endpoint_href`:: The href of the resource endpoint. This is the URL of the
+resource as it appears in the `_links` section of the HAL resource.
+`register`:: The instance of `ModelRegister`.
+
+The `realize` method will automatically handle the URL resolution and fetch
+the resource from the API, and return an instance of the resource class
+defined in the `ModelRegister` (through the endpoint definition of `realize_class`).
+
+NOTE: It is possible to use the `realize` method on a link object using another
+`ModelRegister` instance. This is useful when you want to resolve a link
+using a different API endpoint or a different set of resource models.
+
+.Dynamically realizing a resource from the collection using links
+[example]
+====
+[source,ruby]
 ----
+product_2 = product_index.links.products.last.realize(register)
+# => client.get('/products/2')
+# => {
+#   "id": 2,
+#   "name": "Product 2",
+#   "price": 20.0,
+#   "_links": {
+#     "self": { "href": "/products/2" },
+#     "category": { "href": "/categories/2", "title": "Category 2" },
+#     "related": [
+#        { "href": "/products/4", "title": "Product 4" },
+#        { "href": "/products/6", "title": "Product 6" }
+#     ]
+#   }
+# }
+
+product_2
+# => #<Product id: 2, name: "Product 2", price: 20.0, links:
+#      #<ProductLinks self: <ProductLink href: "/products/2">,
+#                     category: <ProductLink href: "/categories/2", title: "Category 2">,
+#                     related: [
+#                         <ProductLink href: "/products/4", title: "Product 4">,
+#                         <ProductLink href: "/products/6", title: "Product 6">
+#                     ]}>
+----
+====
+
+=== Pagination
+
+HAL index APIs often support pagination, which allows clients to retrieve a
+limited number of resources at a time.
+
+The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs. The
+`Page` class itself is implemented as a `Resource`, so you can use the same
+methods to access the page's attributes and links.
+
+The `Page` class by default supports the following attributes:
 
-=== Working with Collections
+`page`:: The current page number.
+`pages`:: The total number of pages.
+`limit`:: The number of resources per page.
+`total`:: The total number of resources.
+
+Syntax:
 
 [source,ruby]
 ----
-class ProductPage < Lutaml::Hal::Page
-  # Define the relationship between page and items
+class MyPage < Lutaml::Hal::Page
+  # These are typical links given for page objects
+  hal_link :self, key: 'self', realize_class: 'MyPage'
+  hal_link :prev, key: 'prev', realize_class: 'MyPage'
+  hal_link :next, key: 'next', realize_class: 'MyPage'
+  hal_link :first, key: 'first', realize_class: 'MyPage'
+  hal_link :last, key: 'last', realize_class: 'MyPage'
 end
 
-response = client.get('/products')
-products = ProductPage.from_json(response.to_json)
+register.add_endpoint(
+  id: :my_pages,
+  type: :index,
+  url: '/my_pages',
+  model: MyPage
+)
+----
+
+Where,
 
-# Access pagination info
-puts "Page #{products.page} of #{products.pages}, total: #{products.total}"
+`MyPage`:: The class of the page that will be fetched from the API. The class
+must inherit from `Lutaml::Hal::Page`.
+`register`:: The instance of `ModelRegister`.
+`id`:: The ID of the pagination endpoint to be registered in the `ModelRegister`.
+`url`:: The URL of the pagination endpoint.
+`model`:: The class of the page that will be fetched from the API.
 
-# Access linked items
-products.links.products.each do |product|
-  puts "#{product.name}: $#{product.price}"
+
+.Usage example of the Page class
+[example]
+====
+Declaration:
+
+[source,ruby]
+----
+class MyPage < Lutaml::Hal::Page
+  hal_link :self, key: 'self', realize_class: 'MyPage'
+  hal_link :prev, key: 'prev', realize_class: 'MyPage'
+  hal_link :next, key: 'next', realize_class: 'MyPage'
+  hal_link :first, key: 'first', realize_class: 'MyPage'
+  hal_link :last, key: 'last', realize_class: 'MyPage'
 end
+
+register.add_endpoint(
+  id: :my_pages,
+  type: :index,
+  url: '/my_pages',
+  model: MyPage
+)
+----
+
+Usage:
+
+[source,ruby]
+----
+page_1 = register.fetch(:my_pages)
+# => client.get('/my_pages')
+# => {
+#   "page": 1,
+#   "pages": 10,
+#   "limit": 10,
+#   "total": 100,
+#   "_links": {
+#     "self": { "href": "/my_pages" },
+#     "next": { "href": "/my_pages/2" },
+#     "last": { "href": "/my_pages/9" }
+#   }
+# }
+page_1
+# => #<MyPage page: 1, pages: 10, limit: 10, total: 100,
+#      links: #<MyPageLinks self: <MyPageLink href: "/my_pages">,
+#                     next: <MyPageLink href: "/my_pages/2">,
+#                     last: <MyPageLink href: "/my_pages/9">>>
+page_2 = page.links.next.realize(register)
+# => client.get('/my_pages/2')
+# => #<MyPage page: 2, pages: 10, limit: 10, total: 100,
+#      links: #<MyPageLinks self: <MyPageLink href: "/my_pages/2">,
+#                     prev: <MyPageLink href: "/my_pages/1">,
+#                     next: <MyPageLink href: "/my_pages/3">,
+#                     first: <MyPageLink href: "/my_pages/1">,
+#                     last: <MyPageLink href: "/my_pages/9">>>
 ----
+====
 
 
 == License and Copyright

data/lib/lutaml/hal/resource.rb

@@ -14,7 +14,7 @@ module Lutaml
         def inherited(subclass)
           super
           subclass.class_eval do
-            create_links_class
+            create_link_set_class
             init_links_definition
           end
         end
@@ -25,21 +25,31 @@ module Lutaml
         # The "collection" is a boolean indicating if the link
         # is a collection of resources or a single resource
         # The "type" is the type of the link (default is :link, can be :resource)
-        def hal_link(attr_key, key:, realize_class:, collection: false, type: :link)
+        def hal_link(attr_key,
+                     key:,
+                     realize_class:,
+                     link_class: nil,
+                     link_set_class: nil,
+                     collection: false,
+                     type: :link)
           # Use the provided "key" as the attribute name
           attribute_name = attr_key.to_sym
 
           # Create a dynamic Link subclass name based on "realize_class", the
-          # class to realize for a Link object
-          link_klass = create_link_class(realize_class)
-          links_klass = get_links_class
-          links_klass.class_eval do
-            # Declare the corresponding lutaml-model attribute
-            attribute attribute_name, link_klass, collection: collection
-
-            # Define the mapping for the attribute
-            key_value do
-              map attr_key, to: attribute_name
+          # class to realize for a Link object, if `link_class:` is not provided.
+          link_klass = link_class || create_link_class(realize_class)
+
+          # Create a dynamic LinkSet class if `link_set_class:` is not provided.
+          unless link_set_class
+            link_set_klass = link_set_class || get_links_class
+            link_set_klass.class_eval do
+              # Declare the corresponding lutaml-model attribute
+              attribute attribute_name, link_klass, collection: collection
+
+              # Define the mapping for the attribute
+              key_value do
+                map attr_key, to: attribute_name
+              end
             end
           end
 
@@ -59,7 +69,7 @@ module Lutaml
         # This method obtains the Links class that holds the Link classes
         def get_links_class
           parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{name.split('::').last}Links"
+          child_klass_name = "#{name.split('::').last}LinkSet"
           klass_name = "#{parent_klass_name}::#{child_klass_name}"
 
           raise unless Object.const_defined?(klass_name)
@@ -71,22 +81,22 @@ module Lutaml
 
         # The "links" class holds the `_links` object which contains
         # the resource-linked Link classes
-        def create_links_class
+        def create_link_set_class
           parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{name.split('::').last}Links"
+          child_klass_name = "#{name.split('::').last}LinkSet"
           klass_name = "#{parent_klass_name}::#{child_klass_name}"
 
-          # Check if the Links class is already defined, return if so
+          # Check if the LinkSet class is already defined, return if so
           return Object.const_get(klass_name) if Object.const_defined?(klass_name)
 
-          # Define the links class dynamically as a normal Lutaml::Model class
+          # Define the LinkSet class dynamically as a normal Lutaml::Model class
           # since it is not a Resource
           klass = Class.new(Lutaml::Model::Serializable)
           Object.const_get(parent_klass_name).tap do |parent_klass|
             parent_klass.const_set(child_klass_name, klass)
           end
 
-          # Define the Links class with mapping inside the current class
+          # Define the LinkSet class with mapping inside the current class
           class_eval do
             attribute :links, klass
             key_value do

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.0'
+    VERSION = '0.1.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday