w3c_api 0.1.3 → 0.1.4

data/demo/test_embed_functionality.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require_relative 'lib/w3c_api'
+
+puts 'Testing W3C API Embed Functionality'
+puts '=' * 40
+
+# Initialize the client
+client = W3cApi::Client.new
+
+begin
+  puts "\n1. Testing Groups endpoint with embed..."
+  groups_with_embed = client.groups(embed: true, items: 5)
+
+  puts "   Response type: #{groups_with_embed.class}"
+  puts "   Has embedded content: #{groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?('groups')}"
+
+  if groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?('groups')
+    puts "   Available methods: #{groups_with_embed.methods.grep(/embed/).join(', ')}"
+
+    embedded_groups = groups_with_embed.get_embedded('groups')
+    puts "   Number of embedded groups: #{embedded_groups.length}"
+    puts "   First embedded group: #{embedded_groups.first['name'] if embedded_groups.first}"
+  end
+
+  puts "\n2. Testing Specifications endpoint with embed..."
+  specs_with_embed = client.specifications(embed: true, items: 5)
+
+  puts "   Response type: #{specs_with_embed.class}"
+  puts "   Has embedded content: #{specs_with_embed.respond_to?(:has_embedded?) && specs_with_embed.has_embedded?('specifications')}"
+
+  if specs_with_embed.respond_to?(:has_embedded?) && specs_with_embed.has_embedded?('specifications')
+    puts "   Available methods: #{specs_with_embed.methods.grep(/embed/).join(', ')}"
+
+    embedded_specs = specs_with_embed.get_embedded('specifications')
+    puts "   Number of embedded specifications: #{embedded_specs.length}"
+    puts "   First embedded spec: #{embedded_specs.first['title'] if embedded_specs.first}"
+  end
+
+  puts "\n3. Testing comparison: with vs without embed..."
+
+  # Without embed
+  start_time = Time.now
+  client.groups(items: 3)
+  without_embed_time = Time.now - start_time
+  puts "   Without embed: #{without_embed_time.round(3)}s"
+
+  # With embed
+  start_time = Time.now
+  groups_with_embed = client.groups(embed: true, items: 3)
+  with_embed_time = Time.now - start_time
+  puts "   With embed: #{with_embed_time.round(3)}s"
+
+  if groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?('groups')
+    puts '   ✓ Embed functionality working correctly!'
+  else
+    puts '   ⚠ Embed parameter accepted but no embedded content returned'
+  end
+
+  puts "\n4. Testing link realization with embedded content..."
+
+  if groups_with_embed.respond_to?(:links) && groups_with_embed.links.respond_to?(:groups)
+    first_group_link = groups_with_embed.links.groups.first
+    if first_group_link
+      puts "   First group link: #{first_group_link.href}"
+
+      # Test realization with parent_resource (should use embedded data)
+      if first_group_link.respond_to?(:realize)
+        begin
+          realized_group = first_group_link.realize(parent_resource: groups_with_embed)
+          puts '   ✓ Link realization with embedded data successful'
+          puts "   Realized group name: #{realized_group.name if realized_group.respond_to?(:name)}"
+        rescue StandardError => e
+          puts "   ⚠ Link realization failed: #{e.message}"
+        end
+      end
+    end
+  end
+
+  puts "\n✅ Embed functionality test completed successfully!"
+rescue StandardError => e
+  puts "\n❌ Error during testing: #{e.message}"
+  puts 'Backtrace:'
+  puts e.backtrace.first(5).join("\n")
+end

data/lib/w3c_api/client.rb

@@ -7,8 +7,30 @@ require_relative 'hal'
 
 module W3cApi
   class Client
+    # Class method to list endpoints that support embed parameter
+    def self.embed_supported_endpoints
+      hal_instance = W3cApi::Hal.instance
+      endpoints_with_embed = []
+
+      hal_instance.register.models.each do |endpoint_id, endpoint_config|
+        # Check if this endpoint has embed parameter support
+        has_embed = endpoint_config[:parameters].any? do |param|
+          param.name == 'embed' && param.location == :query
+        end
+
+        endpoints_with_embed << endpoint_id if has_embed
+      end
+
+      endpoints_with_embed.sort
+    end
+
+    # Instance method to check if a specific endpoint supports embed
+    def embed_supported?(endpoint_id)
+      self.class.embed_supported_endpoints.include?(endpoint_id)
+    end
+
     # Specification methods
-    def specifications(options = nil)
+    def specifications(options = {})
       fetch_resource(:specification_index, **(options || {}))
     end
 

data/lib/w3c_api/embed.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module W3cApi
+  # Module for discovering and working with embed-supported endpoints
+  module Embed
+    class << self
+      # Get list of endpoints that support embed parameter
+      def supported_endpoints
+        W3cApi::Client.embed_supported_endpoints
+      end
+
+      # Check if a specific endpoint supports embed
+      def supports_embed?(endpoint_id)
+        supported_endpoints.include?(endpoint_id.to_sym)
+      end
+
+      # Get human-readable descriptions of embed-supported endpoints
+      def endpoint_descriptions
+        {
+          specification_index: 'Specifications index with embedded specification details',
+          group_index: 'Groups index with embedded group details',
+          serie_index: 'Series index with embedded series details'
+        }
+      end
+
+      # Get comprehensive embed information
+      def embed_info
+        {
+          supported_endpoints: supported_endpoints,
+          descriptions: endpoint_descriptions,
+          usage_example: {
+            discovery: 'W3cApi::Client.embed_supported_endpoints',
+            usage: 'W3cApi::Client.new.specifications(embed: true, items: 2)',
+            automatic_realization: 'spec_link.realize  # Uses embedded content automatically'
+          }
+        }
+      end
+    end
+  end
+end