w3c_api 0.1.3 → 0.1.5

data/lib/w3c_api/hal.rb

@@ -1,142 +1,271 @@
 # frozen_string_literal: true
 
-require 'singleton'
-require_relative 'models'
+require "singleton"
+require "lutaml/hal"
+require_relative "models"
 
 module W3cApi
+  # Simple parameter class to satisfy lutaml-hal validation requirements
+  class SimpleParameter
+    attr_reader :name, :location, :required, :default_value
+
+    def initialize(name, location: :path, required: false, default_value: nil)
+      @name = name.to_s
+      @location = location
+      @required = required
+      @default_value = default_value
+    end
+
+    def validate!
+      # Simple validation - just ensure name is present
+      if @name.nil? || @name.empty?
+        raise ArgumentError,
+              "Parameter name cannot be empty"
+      end
+    end
+
+    def path_parameter?
+      @location == :path
+    end
+
+    def query_parameter?
+      @location == :query
+    end
+
+    def validate_value(value)
+      # Simple validation - accept any non-nil value
+      !value.nil?
+    end
+  end
+
   class Hal
     include Singleton
 
-    API_URL = 'https://api.w3.org/'
+    API_URL = "https://api.w3.org/"
 
     def initialize
-      setup
+      # Don't call setup here - it will be called when register is first accessed
     end
 
     def client
-      @client ||= Lutaml::Hal::Client.new(api_url: API_URL)
+      @client ||= Lutaml::Hal::Client.new(
+        api_url: API_URL,
+        rate_limiting: rate_limiting_options,
+      )
+    end
+
+    # Configure rate limiting options
+    def rate_limiting_options
+      @rate_limiting_options ||= {
+        enabled: true,
+        max_retries: 3,
+        base_delay: 1.0,
+        max_delay: 60.0,
+        backoff_factor: 2.0,
+      }
+    end
+
+    # Set rate limiting options
+    def configure_rate_limiting(options = {})
+      @rate_limiting_options = rate_limiting_options.merge(options)
+      # Reset client to pick up new options
+      @client = nil
+    end
+
+    # Disable rate limiting
+    def disable_rate_limiting
+      configure_rate_limiting(enabled: false)
+    end
+
+    # Enable rate limiting
+    def enable_rate_limiting
+      configure_rate_limiting(enabled: true)
     end
 
     def register
       return @register if @register
 
       @register = Lutaml::Hal::ModelRegister.new(name: :w3c_api, client: client)
-      Lutaml::Hal::GlobalRegister.instance.register(
-        :w3c_api, @register
-      )
+      Lutaml::Hal::GlobalRegister.instance.register(:w3c_api, @register)
+
+      # Re-run setup to register all endpoints with the new register
+      setup
+
       @register
     end
 
+    def reset_register
+      @register = nil
+    end
+
     private
 
-    # Common pagination query parameters
-    PAGINATION_PARAMS = {
-      'page' => '{page}',
-      'items' => '{items}'
-    }.freeze
+    # Common pagination parameters (simplified without EndpointParameter)
+    def pagination_parameters
+      [
+        SimpleParameter.new("page", location: :query),
+        SimpleParameter.new("items", location: :query),
+      ]
+    end
+
+    # Parameters for endpoints with embed support (simplified without EndpointParameter)
+    def embed_parameters
+      [
+        SimpleParameter.new("embed", location: :query),
+      ] + pagination_parameters
+    end
+
+    # Helper methods for common parameter types (using SimpleParameter)
+    def string_path_param(name, _description = nil)
+      SimpleParameter.new(name, location: :path)
+    end
+
+    def integer_path_param(name, _description = nil)
+      SimpleParameter.new(name, location: :path)
+    end
+
+    def string_query_param(name, _description = nil, required: false)
+      SimpleParameter.new(name, location: :query, required: required)
+    end
 
     # Helper method to add index endpoints with pagination
-    def add_index_endpoint(id, url, model, query_params = PAGINATION_PARAMS)
+    def add_index_endpoint(id, url, model, parameters = pagination_parameters)
       register.add_endpoint(
         id: id,
         type: :index,
         url: url,
         model: model,
-        query_params: query_params
+        parameters: parameters,
       )
     end
 
     # Helper method to add resource endpoints
-    def add_resource_endpoint(id, url, model)
+    def add_resource_endpoint(id, url, model, parameters = [])
       register.add_endpoint(
         id: id,
         type: :resource,
         url: url,
-        model: model
+        model: model,
+        parameters: parameters,
       )
     end
 
-    # Helper method to add nested index endpoints
-    def add_nested_index_endpoints(parent_resource, parent_id_param, endpoints)
-      endpoints.each do |endpoint|
-        add_index_endpoint(
-          :"#{parent_resource}_#{endpoint[:name]}_index",
-          "/#{parent_resource}/#{parent_id_param}/#{endpoint[:path]}",
-          endpoint[:model]
-        )
-      end
-    end
-
-    # Helper method to add individual nested endpoints
-    def add_nested_endpoint(parent_resource, parent_id_param, endpoint_name, endpoint_path, model)
-      add_index_endpoint(
-        :"#{parent_resource}_#{endpoint_name}_index",
-        "/#{parent_resource}/#{parent_id_param}/#{endpoint_path}",
-        model
+    # Helper method to add endpoints with path parameters
+    def add_endpoint_with_path_params(id, type, url, model, path_params = [],
+query_params = [])
+      parameters = (path_params + query_params).compact
+      register.add_endpoint(
+        id: id,
+        type: type,
+        url: url,
+        model: model,
+        parameters: parameters,
       )
     end
 
     def setup
-      # Specification endpoints
+      # Specification endpoints with embed support
       add_index_endpoint(
         :specification_index,
-        '/specifications',
-        Models::SpecificationIndex
-      )
-      add_resource_endpoint(
-        :specification_resource,
-        '/specifications/{shortname}',
-        Models::Specification
+        "/specifications",
+        Models::SpecificationIndex,
+        embed_parameters,
       )
-      add_index_endpoint(
+
+      # Specification by status endpoint
+      add_endpoint_with_path_params(
         :specification_by_status_index,
-        '/specifications',
+        :index,
+        "/specifications",
         Models::SpecificationIndex,
-        { 'status' => '{status}', **PAGINATION_PARAMS }
+        [],
+        [string_query_param("status", required: true)] + pagination_parameters,
+      )
+      add_endpoint_with_path_params(
+        :specification_resource,
+        :resource,
+        "/specifications/{shortname}",
+        Models::Specification,
+        [string_path_param("shortname")],
       )
 
       # Specification version endpoints
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :specification_resource_version_index,
-        '/specifications/{shortname}/versions',
-        Models::SpecVersionIndex
+        :index,
+        "/specifications/{shortname}/versions",
+        Models::SpecVersionIndex,
+        [string_path_param("shortname")],
+        pagination_parameters,
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :specification_resource_version_resource,
-        '/specifications/{shortname}/versions/{version}',
-        Models::SpecVersion
+        :resource,
+        "/specifications/{shortname}/versions/{version}",
+        Models::SpecVersion,
+        [
+          string_path_param("shortname"),
+          string_path_param("version"),
+        ],
       )
 
       # Specification version editors and deliverers
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :specification_version_editors_index,
-        '/specifications/{shortname}/versions/{version}/editors',
-        Models::EditorIndex
-      )
-      add_index_endpoint(
+        :index,
+        "/specifications/{shortname}/versions/{version}/editors",
+        Models::EditorIndex,
+        [
+          string_path_param("shortname"),
+          string_path_param("version"),
+        ],
+        pagination_parameters,
+      )
+      add_endpoint_with_path_params(
         :specification_version_deliverers_index,
-        '/specifications/{shortname}/versions/{version}/deliverers',
-        Models::DelivererIndex
+        :index,
+        "/specifications/{shortname}/versions/{version}/deliverers",
+        Models::DelivererIndex,
+        [
+          string_path_param("shortname"),
+          string_path_param("version"),
+        ],
+        pagination_parameters,
       )
 
       # Specification version predecessors and successors
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :specification_version_predecessors_index,
-        '/specifications/{shortname}/versions/{version}/predecessors',
-        Models::SpecVersionPredecessorIndex
-      )
-      add_index_endpoint(
+        :index,
+        "/specifications/{shortname}/versions/{version}/predecessors",
+        Models::SpecVersionPredecessorIndex,
+        [
+          string_path_param("shortname"),
+          string_path_param("version"),
+        ],
+        pagination_parameters,
+      )
+      add_endpoint_with_path_params(
         :specification_version_successors_index,
-        '/specifications/{shortname}/versions/{version}/successors',
-        Models::SpecVersionSuccessorIndex
+        :index,
+        "/specifications/{shortname}/versions/{version}/successors",
+        Models::SpecVersionSuccessorIndex,
+        [
+          string_path_param("shortname"),
+          string_path_param("version"),
+        ],
+        pagination_parameters,
       )
 
       # Specification related endpoints
       %w[supersedes superseded_by editors deliverers].each do |relation|
-        add_index_endpoint(
+        add_endpoint_with_path_params(
           :"specification_#{relation}_index",
+          :index,
           "/specifications/{shortname}/#{relation.tr('_', '-')}",
-          relation.include?('editor') ? Models::UserIndex : Models::GroupIndex
+          relation.include?("editor") ? Models::UserIndex : Models::GroupIndex,
+          [string_path_param("shortname")],
+          pagination_parameters,
         )
       end
 
@@ -148,86 +277,123 @@ module W3cApi
       #   model: Models::SpecificationIndex
       # )
 
-      # Series endpoints
+      # Series endpoints with embed support
       add_index_endpoint(
         :serie_index,
-        '/specification-series',
-        Models::SerieIndex
+        "/specification-series",
+        Models::SerieIndex,
+        embed_parameters,
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :serie_resource,
-        '/specification-series/{shortname}',
-        Models::Serie
+        :resource,
+        "/specification-series/{shortname}",
+        Models::Serie,
+        [string_path_param("shortname")],
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :serie_specification_resource,
-        '/specification-series/{shortname}/specifications',
-        Models::SpecificationIndex
+        :index,
+        "/specification-series/{shortname}/specifications",
+        Models::SpecificationIndex,
+        [string_path_param("shortname")],
+        pagination_parameters,
       )
 
-      # Group endpoints
+      # Group endpoints with embed support
       add_index_endpoint(
         :group_index,
-        '/groups',
-        Models::GroupIndex
+        "/groups",
+        Models::GroupIndex,
+        embed_parameters,
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :group_resource,
-        '/groups/{id}',
-        Models::Group
+        :resource,
+        "/groups/{id}",
+        Models::Group,
+        [integer_path_param("id")],
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :group_by_type_shortname_resource,
-        '/groups/{type}/{shortname}',
-        Models::Group
-      )
-      add_index_endpoint(
+        :resource,
+        "/groups/{type}/{shortname}",
+        Models::Group,
+        [
+          string_path_param("type"),
+          string_path_param("shortname"),
+        ],
+      )
+      add_endpoint_with_path_params(
         :group_by_type_index,
-        '/groups/{type}',
-        Models::GroupIndex
+        :index,
+        "/groups/{type}",
+        Models::GroupIndex,
+        [string_path_param("type")],
+        pagination_parameters,
       )
       # Group nested endpoints
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :group_specifications_index,
-        '/groups/{id}/specifications',
-        Models::SpecificationIndex
+        :index,
+        "/groups/{id}/specifications",
+        Models::SpecificationIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :group_users_index,
-        '/groups/{id}/users',
-        Models::UserIndex
+        :index,
+        "/groups/{id}/users",
+        Models::UserIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :group_charters_index,
-        '/groups/{id}/charters',
-        Models::CharterIndex
+        :index,
+        "/groups/{id}/charters",
+        Models::CharterIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :group_chairs_index,
-        '/groups/{id}/chairs',
-        Models::ChairIndex
+        :index,
+        "/groups/{id}/chairs",
+        Models::ChairIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :group_team_contacts_index,
-        '/groups/{id}/teamcontacts',
-        Models::TeamContactIndex
+        :index,
+        "/groups/{id}/teamcontacts",
+        Models::TeamContactIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :group_participations_index,
-        '/groups/{id}/participations',
-        Models::ParticipationIndex
+        :index,
+        "/groups/{id}/participations",
+        Models::ParticipationIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
 
       # Translation endpoints
       add_index_endpoint(
         :translation_index,
-        '/translations',
-        Models::TranslationIndex
+        "/translations",
+        Models::TranslationIndex,
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :translation_resource,
-        '/translations/{id}',
-        Models::Translation
+        :resource,
+        "/translations/{id}",
+        Models::Translation,
+        [integer_path_param("id")],
       )
 
       # User endpoints
@@ -238,107 +404,151 @@ module W3cApi
       #   url: '/users',
       #   model: Models::UserIndex
       # )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :user_resource,
-        '/users/{hash}',
-        Models::User
+        :resource,
+        "/users/{hash}",
+        Models::User,
+        [string_path_param("hash")],
       )
 
       # User nested endpoints
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :user_groups_index,
-        '/users/{hash}/groups',
-        Models::GroupIndex
+        :index,
+        "/users/{hash}/groups",
+        Models::GroupIndex,
+        [string_path_param("hash")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :user_affiliations_index,
-        '/users/{hash}/affiliations',
-        Models::AffiliationIndex
+        :index,
+        "/users/{hash}/affiliations",
+        Models::AffiliationIndex,
+        [string_path_param("hash")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :user_participations_index,
-        '/users/{hash}/participations',
-        Models::ParticipationIndex
+        :index,
+        "/users/{hash}/participations",
+        Models::ParticipationIndex,
+        [string_path_param("hash")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :user_chair_of_groups_index,
-        '/users/{hash}/chair-of-groups',
-        Models::GroupIndex
+        :index,
+        "/users/{hash}/chair-of-groups",
+        Models::GroupIndex,
+        [string_path_param("hash")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :user_team_contact_of_groups_index,
-        '/users/{hash}/team-contact-of-groups',
-        Models::GroupIndex
+        :index,
+        "/users/{hash}/team-contact-of-groups",
+        Models::GroupIndex,
+        [string_path_param("hash")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :user_specifications_index,
-        '/users/{hash}/specifications',
-        Models::SpecificationIndex
+        :index,
+        "/users/{hash}/specifications",
+        Models::SpecificationIndex,
+        [string_path_param("hash")],
+        pagination_parameters,
       )
 
       # Affiliation endpoints
       add_index_endpoint(
         :affiliation_index,
-        '/affiliations',
-        Models::AffiliationIndex
+        "/affiliations",
+        Models::AffiliationIndex,
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :affiliation_resource,
-        '/affiliations/{id}',
-        Models::Affiliation
+        :resource,
+        "/affiliations/{id}",
+        Models::Affiliation,
+        [integer_path_param("id")],
       )
 
       # Affiliation nested endpoints
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :affiliation_participants_index,
-        '/affiliations/{id}/participants',
-        Models::ParticipantIndex
+        :index,
+        "/affiliations/{id}/participants",
+        Models::ParticipantIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :affiliation_participations_index,
-        '/affiliations/{id}/participations',
-        Models::ParticipationIndex
+        :index,
+        "/affiliations/{id}/participations",
+        Models::ParticipationIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
 
       # Ecosystem endpoints
       add_index_endpoint(
         :ecosystem_index,
-        '/ecosystems',
-        Models::EcosystemIndex
+        "/ecosystems",
+        Models::EcosystemIndex,
       )
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :ecosystem_resource,
-        '/ecosystems/{shortname}',
-        Models::Ecosystem
+        :resource,
+        "/ecosystems/{shortname}",
+        Models::Ecosystem,
+        [string_path_param("shortname")],
       )
 
       # Ecosystem nested endpoints
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :ecosystem_groups_index,
-        '/ecosystems/{shortname}/groups',
-        Models::GroupIndex
+        :index,
+        "/ecosystems/{shortname}/groups",
+        Models::GroupIndex,
+        [string_path_param("shortname")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :ecosystem_evangelists_index,
-        '/ecosystems/{shortname}/evangelists',
-        Models::EvangelistIndex
+        :index,
+        "/ecosystems/{shortname}/evangelists",
+        Models::EvangelistIndex,
+        [string_path_param("shortname")],
+        pagination_parameters,
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :ecosystem_member_organizations_index,
-        '/ecosystems/{shortname}/member-organizations',
-        Models::AffiliationIndex
+        :index,
+        "/ecosystems/{shortname}/member-organizations",
+        Models::AffiliationIndex,
+        [string_path_param("shortname")],
+        pagination_parameters,
       )
 
       # Participation endpoints
-      add_resource_endpoint(
+      add_endpoint_with_path_params(
         :participation_resource,
-        '/participations/{id}',
-        Models::Participation
+        :resource,
+        "/participations/{id}",
+        Models::Participation,
+        [integer_path_param("id")],
       )
-      add_index_endpoint(
+      add_endpoint_with_path_params(
         :participation_participants_index,
-        '/participations/{id}/participants',
-        Models::ParticipantIndex
+        :index,
+        "/participations/{id}/participants",
+        Models::ParticipantIndex,
+        [integer_path_param("id")],
+        pagination_parameters,
       )
     end
   end