lutaml-hal 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea54d1764e2083f8ba5e232022fa2bae95db1775db65e1be46101c3dc2db3a8
-  data.tar.gz: 3d519340919d3f8d84b5c6a38bc73796fbf662cc40c4a01cc030b3cfad9b00ea
+  metadata.gz: da904351e361ae9657c850d5faf981c6b698583970ead3320f125fdf6078fcbb
+  data.tar.gz: 677a8d713e5c2499cd9250497ca2b6f2d9474e545a2d2b2989dbcd33802b5588
 SHA512:
-  metadata.gz: 31543a34726a0d12557f07aae9d9f70fba8ea936abb0b3f8792d26741ba4f353fcd7b9fd08e2cbff44e91819e18efcb5b67a3c50714752221c58f6a39c7761f1
-  data.tar.gz: 2422ddeeb2903e7adce861fce307594c11f5d147b185121e082ad49fe19156016a940ee9199d6591ab203942c4713e48c0ab3d375bf03d944df5faa914a1b4b1
+  metadata.gz: d1d55faaa7c1f7d45b07a3d475b6908de807f7bed3bfebdfa32ce0ada2b91a1794f948046e0e0c554216f5e18219c07ee81dfb03a2ee0f5fb19e3367821e40fb
+  data.tar.gz: '07085ed8d705dfe5ff1893e1c9d2ab7bc87fe3b22e483dc14edfb1b89b2e54942e21fa38f6c1ff7910030fb57c6ecf198110fa70ef8447a49c377de2935873d8'

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,562 @@ 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
 )
+----
+====
+
+
+[[defining_hal_page_models]]
+=== Defining HAL page models
+
+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. It is a
+subclass of `Resource`, and provides additional attributes and methods for
+handling pagination information
+
+The `Page` class by default supports the following attributes:
+
+`page`:: The current page number.
+`pages`:: The total number of pages.
+`limit`:: The number of resources per page.
+`total`:: The total number of resources.
+
+The way to use the `Page` class is through inheritance from it, where the
+class will automatically create the necessary links for typical page objects.
+
+The typical links of a page object are:
+
+`self`:: A link to the current page.
+`prev`:: A link to the previous page.
+`next`:: A link to the next page.
+`first`:: A link to the first page.
+`last`:: A link to the last page.
+
+The "realize class" of these links are the same as the inherited page
+object, ensuring consistency in the pagination model.
+
+Syntax:
+
+[source,ruby]
+----
+class ProductIndex < Lutaml::Hal::Page
+  # No attributes necessary
+end
+
+register.add_endpoint(
+  id: :product_index,
+  type: :index,
+  url: '/products',
+  model: ProductIndex
+)
 
-register.fetch(:product_index)
-# => client.get('/products')
+page_1 = register.fetch(:product_index)  # Updated to use the correct endpoint id
+page_2_link = page_1.links.next
+# => <#ProductIndexLink href: "/products/2", title: "Next Page">
+----
 
-# => {
-# "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 }
-#   ]
-# }
+Where,
+
+`ProductIndex`:: 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.
+
+
+
+
+== 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 +714,211 @@ product_1
 #                         <ProductLink href: "/products/5", title: "Product 5">
 #                     ]}>
 ----
+====
+
+
+
+=== Fetching a resource index
 
-=== Defining resource models
+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.
+
+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">
+#                     ]>>
+----
+====
+
+
+=== Fetching a resource via link realization
+
+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]
+----
+Lutaml::Model::Link.new(
+  href: 'resource_endpoint_href',
+  # ... other attributes
+).realize(register)
 ----
 
-=== Registering endpoints
+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`.
 
-=== Fetching Resources
+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]
 ----
-# 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)
+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" }
+#     ]
+#   }
+# }
 
-# Follow a link
-category = product_resource.category.realize(register)
+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">
+#                     ]}>
 ----
+====
+
+=== Handling HAL pages / pagination
+
+The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs.
+
+As described in <<defining_hal_page_models>>, subclassing the `Page` class
+provides pagination capabilities, including the management of links to navigate
+through pages of resources.
 
-=== Working with Collections
+
+.Usage example of the Page class
+[example]
+====
+Declaration:
 
 [source,ruby]
 ----
-class ProductPage < Lutaml::Hal::Page
-  # Define the relationship between page and items
+class ResourceIndex < Lutaml::Hal::Page
+  # No attribute definition necessary
 end
 
-response = client.get('/products')
-products = ProductPage.from_json(response.to_json)
+register.add_endpoint(
+  id: :resource_index,
+  type: :index,
+  url: '/resources',
+  model: ResourceIndex
+)
+----
 
-# Access pagination info
-puts "Page #{products.page} of #{products.pages}, total: #{products.total}"
+Usage:
 
-# Access linked items
-products.links.products.each do |product|
-  puts "#{product.name}: $#{product.price}"
-end
+[source,ruby]
+----
+page_1 = register.fetch(:resource_index)
+# => client.get('/resources')
+# => {
+#   "page": 1,
+#   "pages": 10,
+#   "limit": 10,
+#   "total": 100,
+#   "_links": {
+#     "self": {
+#       "href": "https://api.example.com/resources?page=1&items=10"
+#     },
+#     "first": {
+#       "href": "https://api.example.com/resources?page=1&items=10"
+#     },
+#     "last": {
+#       "href": "https://api.example.com/resources?page=10&items=10"
+#     },
+#     "next": {
+#       "href": "https://api.example.com/resources?page=2&items=10"
+#     }
+#   }
+# }
+
+page_1
+# => #<ResourceIndex page: 1, pages: 10, limit: 10, total: 100,
+#      links: #<ResourceIndexLinks
+#                self: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                next: #<ResourceIndexLink href: "/resources?page=2&items=10">,
+#                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>
+
+page_2 = page.links.next.realize(register)
+# => client.get('/resources?page=2&items=10')
+# => #<ResourceIndex page: 2, pages: 10, limit: 10, total: 100,
+#      links: #<ResourceIndexLinks
+#                self: #<ResourceIndexLink href: "/resources?page=2&items=10">,
+#                prev: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                next: #<ResourceIndexLink href: "/resources?page=3&items=10">,
+#                first: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>,
+#                prev: #<ResourceIndexLink href: "/resources?page=1&items=10">>>
 ----
+====
 
 
 == License and Copyright

data/lib/lutaml/hal/page.rb

@@ -19,6 +19,19 @@ module Lutaml
         map 'pages', to: :pages
         map 'total', to: :total
       end
+
+      def self.inherited(subclass)
+        super
+
+        page_links_symbols = %i[self next prev first last]
+        subclass_name = subclass.name
+        subclass.class_eval do
+          # Define common page links
+          page_links_symbols.each do |link_symbol|
+            hal_link link_symbol, key: link_symbol.to_s, realize_class: subclass_name
+          end
+        end
+      end
     end
   end
 end

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,8 +69,8 @@ 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"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          child_klass_name = "#{name.split('::').last}LinkSet"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
           raise unless Object.const_defined?(klass_name)
 
@@ -71,22 +81,21 @@ 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"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          child_klass_name = "#{name.split('::').last}LinkSet"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
-          # 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
+          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
+          parent_klass.const_set(child_klass_name, klass)
 
-          # 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
@@ -103,7 +112,7 @@ module Lutaml
         def create_link_class(realize_class_name)
           parent_klass_name = name.split('::')[0..-2].join('::')
           child_klass_name = "#{name.split('::').last}Link"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
           return Object.const_get(klass_name) if Object.const_defined?(klass_name)
 
@@ -112,9 +121,9 @@ module Lutaml
             # Define the link class with the specified key and class
             attribute :type, :string, default: realize_class_name
           end
-          Object.const_get(parent_klass_name).tap do |parent_klass|
-            parent_klass.const_set(child_klass_name, klass)
-          end
+
+          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
+          parent_klass.const_set(child_klass_name, klass)
 
           klass
         end

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.0'
+    VERSION = '0.1.3'
   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.3
 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