feat: add API to return downstream data for an upstream library content

Author: rpenido

cms/djangoapps/contentstore/migrations/0010_publishableentitylink_downstream_parent_usage_key.py

@@ -0,0 +1,30 @@
+# Generated by Django 4.2.18 on 2025-02-19 23:32
+
+from django.db import migrations
+from opaque_keys.edx.django.models import UsageKeyField
+from opaque_keys.edx.keys import UsageKey
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('contentstore', '0009_learningcontextlinksstatus_publishableentitylink'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='publishableentitylink',
+            name='downstream_parent_usage_key',
+            field=UsageKeyField(
+                db_index=True,
+                # Adds a default invalid value to the field to prevent the migration from failing
+                default=UsageKey.from_string('block-v1:edX+DemoX+Demo_Course+type@vertical+block@invalid'),
+                max_length=255
+            ),
+        ),
+        migrations.AlterField(
+            model_name='publishableentitylink',
+            name='downstream_parent_usage_key',
+            field=UsageKeyField(db_index=True, max_length=255),
+        ),
+    ]

cms/djangoapps/contentstore/models.py

@@ -106,6 +106,8 @@ class PublishableEntityLink(models.Model):
     # A downstream entity can only link to single upstream entity
     # whereas an entity can be upstream for multiple downstream entities.
     downstream_usage_key = UsageKeyField(max_length=255, unique=True)
+    # Search by parent key (i.e., unit key)
+    downstream_parent_usage_key = UsageKeyField(max_length=255, db_index=True)
     # Search by course/downstream key
     downstream_context_key = CourseKeyField(max_length=255, db_index=True)
     version_synced = models.IntegerField()
@@ -147,6 +149,7 @@ def update_or_create(
         upstream_usage_key: UsageKey,
         upstream_context_key: str,
         downstream_usage_key: UsageKey,
+        downstream_parent_usage_key: UsageKey,
         downstream_context_key: CourseKey,
         version_synced: int,
         version_declined: int | None = None,
@@ -161,6 +164,7 @@ def update_or_create(
             'upstream_usage_key': upstream_usage_key,
             'upstream_context_key': upstream_context_key,
             'downstream_usage_key': downstream_usage_key,
+            'downstream_parent_usage_key': downstream_parent_usage_key,
             'downstream_context_key': downstream_context_key,
             'version_synced': version_synced,
             'version_declined': version_declined,
@@ -202,6 +206,15 @@ def get_by_downstream_context(cls, downstream_context_key: CourseKey) -> QuerySe
             "upstream_block__learning_package"
         )
 
+    @classmethod
+    def get_by_upstream_usage_key(cls, upstream_usage_key: UsageKey) -> QuerySet["PublishableEntityLink"]:
+        """
+        Get all downstream context keys for given upstream usage key
+        """
+        return cls.objects.filter(
+            upstream_usage_key=upstream_usage_key,
+        )
+
 
 class LearningContextLinksStatusChoices(models.TextChoices):
     """

cms/djangoapps/contentstore/rest_api/v2/urls.py

@@ -29,6 +29,11 @@
         downstreams.UpstreamListView.as_view(),
         name='upstream-list'
     ),
+    re_path(
+        f'^upstream/{settings.USAGE_KEY_PATTERN}/downstream-contexts$',
+        downstreams.DownstreamContextListView.as_view(),
+        name='downstream-context-list'
+    ),
     re_path(
         fr'^downstreams/{settings.USAGE_KEY_PATTERN}/sync$',
         downstreams.SyncFromUpstreamView.as_view(),

cms/djangoapps/contentstore/rest_api/v2/views/downstreams.py

@@ -40,6 +40,11 @@
       400: Downstream block is not linked to upstream content.
       404: Downstream block not found or user lacks permission to edit it.
 
+  /api/contentstore/v2/upstream/{usage_key_string}/downstream-contexts
+
+    GET: List all downstream contexts (Courses) linked to a library block.
+        200: A list of Course IDs and their display names and URLs.
+
   # NOT YET IMPLEMENTED -- Will be needed for full Libraries Relaunch in ~Teak.
   /api/contentstore/v2/downstreams
   /api/contentstore/v2/downstreams?course_id=course-v1:A+B+C&ready_to_sync=true
@@ -61,6 +66,8 @@
 
 from attrs import asdict as attrs_asdict
 from django.contrib.auth.models import User  # pylint: disable=imported-auth-user
+from django.utils.translation import gettext_lazy as _
+from itertools import groupby
 from opaque_keys import InvalidKeyError
 from opaque_keys.edx.keys import CourseKey, UsageKey
 from rest_framework.exceptions import NotFound, ValidationError
@@ -71,6 +78,7 @@
 
 from cms.djangoapps.contentstore.helpers import import_static_assets_for_library_sync
 from cms.djangoapps.contentstore.models import PublishableEntityLink
+from cms.djangoapps.contentstore.utils import reverse_course_url, reverse_usage_url
 from cms.djangoapps.contentstore.rest_api.v2.serializers import PublishableEntityLinksSerializer
 from cms.lib.xblock.upstream_sync import (
     BadDownstream,
@@ -137,6 +145,55 @@ def get(self, request: _AuthenticatedRequest, course_key_string: str):
         return Response(serializer.data)
 
 
+@view_auth_classes()
+class DownstreamContextListView(DeveloperErrorViewMixin, APIView):
+    """
+    Serves library block->course->unit links
+    """
+    def get(self, request: _AuthenticatedRequest, usage_key_string: str) -> Response:
+        """
+        Fetches downstream links for given publishable entity
+        """
+        try:
+            usage_key = UsageKey.from_string(usage_key_string)
+        except InvalidKeyError as exc:
+            raise ValidationError(detail=f"Malformed usage key: {usage_key_string}") from exc
+
+        links = (
+            PublishableEntityLink
+                .get_by_upstream_usage_key(upstream_usage_key=usage_key)
+                .order_by("downstream_context_key", "downstream_parent_usage_key")
+                .values( "downstream_usage_key", "downstream_context_key", "downstream_parent_usage_key")
+        )
+
+        result = []
+        for context_key, links_by_context in groupby(links, lambda link: link["downstream_context_key"]):
+            # Pre-fetch the course with all of its children:
+            course = modulestore().get_course(context_key, depth=None)
+            if course is None:
+                raise BadDownstream(_("Course {context_key} not found").format(context_key=context_key))
+            course_link = {
+                "id": str(context_key),
+                "display_name": course.display_name,
+                "url": reverse_course_url("course_handler", context_key),
+                "units": []
+            }
+            for unit_key, links_by_unit  in groupby(links_by_context, lambda link: link["downstream_parent_usage_key"]):
+                unit_link = {
+                    "id": str(unit_key),
+                    "url": reverse_usage_url("container_handler", unit_key),
+                    "links": []
+                }
+                for downstream_link in links_by_unit:
+                    unit_link["links"].append({
+                        "id": str(downstream_link["downstream_usage_key"]),
+                    })
+                course_link["units"].append(unit_link)
+            result.append(course_link)
+
+        return Response(result)
+
+
 @view_auth_classes(is_authenticated=True)
 class DownstreamView(DeveloperErrorViewMixin, APIView):
     """

cms/djangoapps/contentstore/rest_api/v2/views/tests/test_downstreams.py

@@ -10,6 +10,7 @@
 from cms.djangoapps.contentstore.helpers import StaticFileNotices
 from cms.lib.xblock.upstream_sync import BadUpstream, UpstreamLink
 from common.djangoapps.student.tests.factories import UserFactory
+from openedx.core.djangoapps.content.course_overviews.tests.factories import CourseOverviewFactory
 from xmodule.modulestore.django import modulestore
 from xmodule.modulestore.tests.django_utils import SharedModuleStoreTestCase
 from xmodule.modulestore.tests.factories import BlockFactory, CourseFactory
@@ -56,6 +57,7 @@ def setUp(self):
         freezer.start()
         self.maxDiff = 2000
         self.course = CourseFactory.create()
+        CourseOverviewFactory.create(id=self.course.id, display_name=self.course.display_name)
         chapter = BlockFactory.create(category='chapter', parent=self.course)
         sequential = BlockFactory.create(category='sequential', parent=chapter)
         unit = BlockFactory.create(category='vertical', parent=sequential)
@@ -66,6 +68,18 @@ def setUp(self):
         self.downstream_html_key = BlockFactory.create(
             category='html', parent=unit, upstream=MOCK_HTML_UPSTREAM_REF, upstream_version=1,
         ).usage_key
+
+        self.another_course = CourseFactory.create(display_name="Another Course")
+        CourseOverviewFactory.create(id=self.another_course.id, display_name=self.another_course.display_name)
+        another_chapter = BlockFactory.create(category='chapter', parent=self.another_course)
+        another_sequential = BlockFactory.create(category='sequential', parent=another_chapter)
+        another_unit = BlockFactory.create(category='vertical', parent=another_sequential)
+        for _ in range(3):
+            # Adds 3 videos linked to the same upstream
+            BlockFactory.create(
+                category='video', parent=another_unit, upstream=MOCK_UPSTREAM_REF, upstream_version=123,
+            )
+
         self.fake_video_key = self.course.id.make_usage_key("video", "NoSuchVideo")
         self.superuser = UserFactory(username="superuser", password="password", is_staff=True, is_superuser=True)
         self.learner = UserFactory(username="learner", password="password")
@@ -339,3 +353,34 @@ def test_200_all_upstreams(self):
             },
         ]
         self.assertListEqual(data, expected)
+
+
+class GetDownstreamContextsTest(_BaseDownstreamViewTestMixin, SharedModuleStoreTestCase):
+    """
+    Test that `GET /api/v2/contentstore/upstream/:usage_key/downstream-contexts returns list of
+    link contexts (i.e. courses) in given upstream entity (i.e. library block).
+    """
+    def call_api(self, usage_key_string):
+        return self.client.get(f"/api/contentstore/v2/upstream/{usage_key_string}/downstream-contexts")
+
+    def test_200_downstream_context_list(self):
+        """
+        Returns all downstream courses for given library block
+        """
+        self.client.login(username="superuser", password="password")
+        response = self.call_api(MOCK_UPSTREAM_REF)
+        assert response.status_code == 200
+        data = response.json()
+        expected = [
+            {
+                'id': str(self.course.id),
+                'display_name': str(self.course.display_name),
+                'url': f'/course/{str(self.course.id)}',
+            },
+            {
+                'id': str(self.another_course.id),
+                'display_name': str(self.another_course.display_name),
+                'url': f'/course/{str(self.another_course.id)}',
+            },
+        ]
+        self.assertListEqual(data, expected)

cms/djangoapps/contentstore/utils.py

@@ -2383,6 +2383,8 @@ def create_or_update_xblock_upstream_link(xblock, course_key: str | CourseKey, c
     except ObjectDoesNotExist:
         log.error(f"Library component not found for {upstream_usage_key}")
         lib_component = None
+
+    print(f"!!!!!!!!!!!!!!!!! xblock.parent -> {xblock.parent}")
     PublishableEntityLink.update_or_create(
         lib_component,
         upstream_usage_key=xblock.upstream,