(#990) Add depth parameter to GET /resources/:ctid (#1007)

Author: excelsior

app/api/v1/resources.rb

@@ -91,6 +91,11 @@ class Resources < MountableAPI
           desc 'Return a resource.'
           params do
             requires :id, type: String, desc: 'Resource id.'
+            optional :depth,
+                     type: Integer,
+                     default: 0,
+                     desc: 'Maximum depth for nested blank nodes.',
+                     values: ->(value) { value >= 0 }
           end
           before do
             authenticate_community!
@@ -99,7 +104,8 @@ class Resources < MountableAPI
             resource = FetchEnvelopeResource
                        .new(
                          envelope_community: current_community,
-                         resource_id: params[:id]
+                         resource_id: params[:id],
+                         depth: params[:depth]
                        )
                        .resource
 

app/services/fetch_envelope_resource.rb

@@ -1,14 +1,15 @@
 class FetchEnvelopeResource # rubocop:todo Style/Documentation
   BNODE_ID_REGEX = '(?<=")_:[^"]+(?=")'.freeze
 
-  attr_reader :envelope_community, :resource_id
+  attr_reader :envelope_community, :resource_id, :depth
 
   delegate :connection, to: ActiveRecord::Base
   delegate :quote, to: :connection
 
-  def initialize(envelope_community:, resource_id:)
+  def initialize(envelope_community:, resource_id:, depth: nil)
     @envelope_community = envelope_community
     @resource_id = resource_id&.downcase
+    @depth = depth
   end
 
   def query
@@ -43,6 +44,7 @@ def query
         ) bnodes
         ON envelope_resources.resource_id = bnodes.resource_id
         WHERE NOT envelope_resources.resource_id = ANY(bnodes.path)
+        AND #{depth_recursion_condition}
         AND envelopes.deleted_at IS NULL
         AND envelopes.envelope_community_id = #{envelope_community.id}
       )
@@ -74,4 +76,12 @@ def resource
       result.first.fetch('resource')
     end
   end
+
+  private
+
+  def depth_recursion_condition
+    return 'TRUE' if depth.nil?
+
+    "cardinality(bnodes.path) <= #{depth.to_i}"
+  end
 end

lib/swagger_docs/sections/resources.rb

@@ -208,6 +208,14 @@ module Resources # rubocop:todo Metrics/ModuleLength, Style/Documentation
 
               parameter community_name
               parameter resource_id
+              parameter name: :depth,
+                        in: :query,
+                        type: :integer,
+                        format: :int32,
+                        default: 0,
+                        required: false,
+                        minimum: 0,
+                        description: 'Maximum depth for nested blank nodes'
 
               response 200 do
                 key :description, 'Retrieves a resource by identifier'

spec/api/v1/resources_spec.rb

@@ -24,20 +24,30 @@
       let(:resource_with_ids) do
         resource.merge('@id' => full_id, 'ceterms:ctid' => ctid)
       end
+      let(:extract_resources) { false }
+      let(:request_params) { {} }
+      let(:request_path) do
+        path = "/resources/#{CGI.escape(id).upcase}"
+        return path if request_params.empty?
+
+        "#{path}?#{Rack::Utils.build_query(request_params)}"
+      end
 
       before do
         allow_any_instance_of(EnvelopeCommunity) # rubocop:todo RSpec/AnyInstance
           .to receive(:id_field).and_return(id_field)
 
-        create(
+        envelope = create(
           :envelope,
           :from_cer,
           :with_cer_credential,
           envelope_community: ec,
           processed_resource: resource_with_ids
         )
 
-        get "/resources/#{CGI.escape(id).upcase}"
+        ExtractEnvelopeResources.call(envelope:) if extract_resources
+
+        get request_path
       end
 
       # rubocop:todo RSpec/MultipleMemoizedHelpers
@@ -257,6 +267,120 @@
         end
         # rubocop:enable RSpec/MultipleMemoizedHelpers
       end
+
+      # rubocop:todo RSpec/NestedGroups, RSpec/MultipleMemoizedHelpers
+      context 'with `depth` query param' do # rubocop:todo RSpec/MultipleMemoizedHelpers, RSpec/NestedGroups
+        # rubocop:enable RSpec/NestedGroups, RSpec/MultipleMemoizedHelpers
+        let(:id_field) { 'ceterms:ctid' }
+        let(:id) { ctid }
+        let(:extract_resources) { true }
+        let(:parent_bnode_id) { "_:#{Envelope.generate_ctid}" }
+        let(:child_bnode_id) { "_:#{Envelope.generate_ctid}" }
+        let(:request_params) { { depth: depth } }
+        let(:resource_with_ids) do
+          {
+            '@id' => "https://credentialengineregistry.org/graph/#{ctid}",
+            '@type' => 'ceasn:CompetencyFramework',
+            '@context' => 'http://credreg.net/ctdlasn/schema/context/json',
+            '@graph' => [main_resource, parent_nested_resource, child_nested_resource]
+          }
+        end
+        let(:main_resource) do
+          {
+            '@id' => full_id,
+            '@type' => 'ceasn:CompetencyFramework',
+            'ceterms:ctid' => ctid,
+            'ceasn:hasTopChild' => [{ '@id' => parent_bnode_id }]
+          }
+        end
+        let(:parent_nested_resource) do
+          {
+            '@id' => parent_bnode_id,
+            '@type' => 'ceasn:Competency',
+            'ceasn:narrowAlignment' => [{ '@id' => child_bnode_id }]
+          }
+        end
+        let(:child_nested_resource) do
+          {
+            '@id' => child_bnode_id,
+            '@type' => 'ceasn:Competency'
+          }
+        end
+
+        # rubocop:todo RSpec/NestedGroups
+        # rubocop:todo RSpec/MultipleMemoizedHelpers
+        context 'when depth is 0' do # rubocop:todo RSpec/NestedGroups
+          # rubocop:enable RSpec/NestedGroups
+          let(:depth) { 0 }
+
+          it 'does not include nested blank nodes' do
+            expect_status(:ok)
+            expect(JSON(response.body).fetch('@included', [])).to be_empty
+          end
+        end
+        # rubocop:enable RSpec/MultipleMemoizedHelpers
+
+        # rubocop:todo RSpec/NestedGroups
+        # rubocop:todo RSpec/MultipleMemoizedHelpers
+        context 'when depth is omitted' do # rubocop:todo RSpec/NestedGroups
+          # rubocop:enable RSpec/NestedGroups
+          let(:request_params) { {} }
+
+          it 'defaults to 0 depth' do
+            expect_status(:ok)
+            expect(JSON(response.body).fetch('@included', [])).to be_empty
+          end
+        end
+        # rubocop:enable RSpec/MultipleMemoizedHelpers
+
+        # rubocop:todo RSpec/NestedGroups
+        # rubocop:todo RSpec/MultipleMemoizedHelpers
+        context 'when depth is 1' do # rubocop:todo RSpec/NestedGroups
+          # rubocop:enable RSpec/NestedGroups
+          let(:depth) { 1 }
+
+          it 'includes first-level blank nodes only' do
+            expect_status(:ok)
+            included_ids = JSON(response.body)
+                           .fetch('@included', [])
+                           .map { |item| item.fetch('@id') }
+            expect(
+              included_ids
+            ).to contain_exactly(parent_bnode_id)
+          end
+        end
+        # rubocop:enable RSpec/MultipleMemoizedHelpers
+
+        # rubocop:todo RSpec/NestedGroups
+        # rubocop:todo RSpec/MultipleMemoizedHelpers
+        context 'when depth is 2' do # rubocop:todo RSpec/NestedGroups
+          # rubocop:enable RSpec/NestedGroups
+          let(:depth) { 2 }
+
+          it 'includes nested blank nodes up to the requested depth' do
+            expect_status(:ok)
+            included_ids = JSON(response.body)
+                           .fetch('@included', [])
+                           .map { |item| item.fetch('@id') }
+            expect(
+              included_ids
+            ).to contain_exactly(parent_bnode_id, child_bnode_id)
+          end
+        end
+        # rubocop:enable RSpec/MultipleMemoizedHelpers
+
+        # rubocop:todo RSpec/NestedGroups
+        # rubocop:todo RSpec/MultipleMemoizedHelpers
+        context 'when depth is negative' do # rubocop:todo RSpec/NestedGroups
+          # rubocop:enable RSpec/NestedGroups
+          let(:depth) { -1 }
+
+          it 'returns bad_request' do
+            expect_status(:bad_request)
+          end
+        end
+        # rubocop:enable RSpec/MultipleMemoizedHelpers
+      end
     end
     # rubocop:enable RSpec/MultipleMemoizedHelpers