feat: Add Content Groups V2 JSON REST API

Implements a pure JSON REST API for fetching content group configurations, replacing the legacy HTML+JSON hybrid endpoint with a RESTful interface.

Author: brianjbuck-wgu

cms/djangoapps/contentstore/course_group_config.py

@@ -12,23 +12,19 @@
 from cms.djangoapps.contentstore.utils import reverse_usage_url
 from common.djangoapps.util.db import MYSQL_MAX_INT, generate_int_id
 from lms.lib.utils import get_parent_unit
+from openedx.core.djangoapps.course_groups.constants import (
+    COHORT_SCHEME,
+    CONTENT_GROUP_CONFIGURATION_DESCRIPTION,
+    CONTENT_GROUP_CONFIGURATION_NAME,
+    RANDOM_SCHEME,
+)
 from openedx.core.djangoapps.course_groups.partition_scheme import get_cohorted_user_partition
 from xmodule.partitions.partitions import MINIMUM_UNUSED_PARTITION_ID, ReadOnlyUserPartitionError, UserPartition  # lint-amnesty, pylint: disable=wrong-import-order
 from xmodule.partitions.partitions_service import get_all_partitions_for_course  # lint-amnesty, pylint: disable=wrong-import-order
 from xmodule.split_test_block import get_split_user_partitions  # lint-amnesty, pylint: disable=wrong-import-order
 
 MINIMUM_GROUP_ID = MINIMUM_UNUSED_PARTITION_ID
 
-RANDOM_SCHEME = "random"
-COHORT_SCHEME = "cohort"
-ENROLLMENT_SCHEME = "enrollment_track"
-
-CONTENT_GROUP_CONFIGURATION_DESCRIPTION = _(
-    'The groups in this configuration can be mapped to cohorts in the Instructor Dashboard.'
-)
-
-CONTENT_GROUP_CONFIGURATION_NAME = _('Content Groups')
-
 log = logging.getLogger(__name__)
 
 

cms/djangoapps/contentstore/rest_api/v2/serializers/__init__.py

@@ -9,9 +9,9 @@
 from cms.djangoapps.contentstore.rest_api.v2.serializers.home import CourseHomeTabSerializerV2
 
 __all__ = [
-    'CourseHomeTabSerializerV2',
     'ComponentLinksSerializer',
-    'PublishableEntityLinkSerializer',
     'ContainerLinksSerializer',
+    'CourseHomeTabSerializerV2',
+    'PublishableEntityLinkSerializer',
     'PublishableEntityLinksSummarySerializer',
 ]

cms/djangoapps/contentstore/utils.py

@@ -2173,8 +2173,11 @@ def get_group_configurations_context(course, store):
     It is used for both DRF and django views.
     """
 
-    from cms.djangoapps.contentstore.course_group_config import (
-        COHORT_SCHEME, ENROLLMENT_SCHEME, GroupConfiguration, RANDOM_SCHEME
+    from cms.djangoapps.contentstore.course_group_config import GroupConfiguration
+    from openedx.core.djangoapps.course_groups.constants import (
+        COHORT_SCHEME,
+        ENROLLMENT_SCHEME,
+        RANDOM_SCHEME,
     )
     from cms.djangoapps.contentstore.views.course import (
         are_content_experiments_enabled

cms/djangoapps/contentstore/views/tests/test_group_configurations.py

@@ -11,12 +11,12 @@
 import ddt
 
 from cms.djangoapps.contentstore import toggles
-from cms.djangoapps.contentstore.course_group_config import (
+from cms.djangoapps.contentstore.course_group_config import GroupConfiguration
+from cms.djangoapps.contentstore.tests.utils import CourseTestCase
+from openedx.core.djangoapps.course_groups.constants import (
     CONTENT_GROUP_CONFIGURATION_NAME,
     ENROLLMENT_SCHEME,
-    GroupConfiguration
 )
-from cms.djangoapps.contentstore.tests.utils import CourseTestCase
 from cms.djangoapps.contentstore.utils import reverse_course_url, reverse_usage_url
 from openedx.features.content_type_gating.helpers import CONTENT_GATING_PARTITION_ID
 from openedx.features.content_type_gating.partitions import CONTENT_TYPE_GATING_SCHEME

lms/djangoapps/instructor/docs/references/instructor-v2-content-groups-api-spec.yaml

@@ -0,0 +1,313 @@
+swagger: '2.0'
+
+info:
+  title: Content Groups API
+  version: 2.0.0
+  description: |
+    RESTful API for retrieving content groups (user partitions with cohort scheme) in courses.
+
+    Content groups enable course creators to assign different course content to different learner cohorts.
+    This API allows instructors and staff to retrieve content group configurations for their courses.
+
+    **Note**: This is the v2 JSON-only API endpoint in the Instructor Dashboard API.
+    The legacy v1 endpoint returns HTML with embedded JSON.
+
+    **Current Status**: This is a read-only API. Write operations (POST/PUT/DELETE) are not yet implemented.
+
+host: edx.example.com
+basePath: /api/instructor/v2
+schemes:
+  - https
+
+securityDefinitions:
+  jwt:
+    type: apiKey
+    name: Authorization
+    in: header
+    description: "JWT token format: Bearer <token>"
+  session:
+    type: basic
+    description: Session-based authentication for staff users
+
+security:
+  - jwt: []
+  - session: []
+
+tags:
+  - name: Content Groups
+    description: Retrieve content group configurations for courses
+
+paths:
+  /courses/{course_id}/group_configurations:
+    get:
+      tags:
+        - Content Groups
+      summary: List all content groups for a course
+      description: |
+        Retrieves all content group configurations (user partitions with scheme='cohort') for a specified course.
+
+        Content groups are used to organize learners into cohorts and assign differentiated course content.
+        This endpoint returns only cohort-scheme partitions; other partition types (enrollment_track, experiments) are excluded.
+
+        If no content group exists, an empty content group partition is automatically created.
+      operationId: listContentGroups
+      produces:
+        - application/json
+      parameters:
+        - $ref: '#/parameters/CourseId'
+      responses:
+        200:
+          description: Successfully retrieved content groups
+          schema:
+            $ref: '#/definitions/ContentGroupsListResponse'
+          examples:
+            application/json:
+              all_group_configurations:
+                - id: 50
+                  name: Content Groups
+                  scheme: cohort
+                  description: The groups in this configuration can be mapped to cohorts in the Instructor Dashboard.
+                  parameters: {}
+                  groups:
+                    - id: 1
+                      name: Content Group A
+                      version: 1
+                      usage: []
+                    - id: 2
+                      name: Content Group B
+                      version: 1
+                      usage: []
+                    - id: 3
+                      name: Test
+                      version: 1
+                      usage: []
+                  active: true
+                  version: 3
+                  read_only: false
+              should_show_enrollment_track: false
+              should_show_experiment_groups: true
+              context_course: null
+              group_configuration_url: /api/instructor/v2/courses/course-v1:org+course+run/group_configurations
+              course_outline_url: /api/contentstore/v1/courses/course-v1:org+course+run/outline
+        400:
+          $ref: '#/responses/BadRequest'
+        401:
+          $ref: '#/responses/Unauthorized'
+        403:
+          $ref: '#/responses/Forbidden'
+        404:
+          $ref: '#/responses/CourseNotFound'
+
+  /courses/{course_id}/group_configurations/{configuration_id}:
+    get:
+      tags:
+        - Content Groups
+      summary: Retrieve a specific content group configuration
+      description: |
+        Retrieves the details of a single content group configuration by its ID.
+
+        Returns all metadata including groups, partition scheme, and usage information.
+      operationId: getContentGroup
+      produces:
+        - application/json
+      parameters:
+        - $ref: '#/parameters/CourseId'
+        - $ref: '#/parameters/ConfigurationId'
+      responses:
+        200:
+          description: Content group configuration details
+          schema:
+            $ref: '#/definitions/ContentGroupResponse'
+        401:
+          $ref: '#/responses/Unauthorized'
+        403:
+          $ref: '#/responses/Forbidden'
+        404:
+          $ref: '#/responses/ContentGroupNotFound'
+
+parameters:
+  CourseId:
+    name: course_id
+    in: path
+    required: true
+    type: string
+    format: opaque-key
+    description: "The course key (e.g., course-v1:org+course+run)"
+    example: "course-v1:edX+DemoX+Demo_2024"
+
+  ConfigurationId:
+    name: configuration_id
+    in: path
+    required: true
+    type: integer
+    description: The ID of the content group configuration
+    example: 50
+
+responses:
+  BadRequest:
+    description: Invalid request parameters or body
+    schema:
+      $ref: '#/definitions/ErrorResponse'
+    examples:
+      application/json:
+        error: "Invalid parameters"
+
+  Unauthorized:
+    description: Authentication required
+    schema:
+      $ref: '#/definitions/ErrorResponse'
+    examples:
+      application/json:
+        error: "Authentication credentials were not provided"
+
+  Forbidden:
+    description: User does not have permission to access this resource
+    schema:
+      $ref: '#/definitions/ErrorResponse'
+    examples:
+      application/json:
+        error: "You do not have permission to perform this action"
+
+  CourseNotFound:
+    description: Course not found
+    schema:
+      $ref: '#/definitions/ErrorResponse'
+    examples:
+      application/json:
+        error: "Course not found"
+
+  ContentGroupNotFound:
+    description: Content group configuration not found
+    schema:
+      $ref: '#/definitions/ErrorResponse'
+    examples:
+      application/json:
+        error: "Content group configuration not found"
+
+definitions:
+  ContentGroupsListResponse:
+    type: object
+    description: Response containing all content groups for a course
+    required:
+      - all_group_configurations
+      - should_show_enrollment_track
+      - should_show_experiment_groups
+    properties:
+      all_group_configurations:
+        type: array
+        description: List of content group configurations (only scheme='cohort' partitions)
+        items:
+          $ref: '#/definitions/ContentGroupResponse'
+      should_show_enrollment_track:
+        type: boolean
+        description: Whether enrollment track groups should be displayed
+      should_show_experiment_groups:
+        type: boolean
+        description: Whether experiment groups should be displayed
+      context_course:
+        type: object
+        nullable: true
+        description: Course context object (null in API responses)
+      group_configuration_url:
+        type: string
+        description: Base URL for accessing individual group configurations
+      course_outline_url:
+        type: string
+        description: URL to the course outline page
+
+  ContentGroupResponse:
+    type: object
+    description: A single content group configuration with all its metadata
+    required:
+      - id
+      - name
+      - scheme
+      - description
+      - groups
+      - active
+      - version
+      - parameters
+      - read_only
+    properties:
+      id:
+        type: integer
+        description: Unique identifier for this content group configuration
+        example: 50
+      name:
+        type: string
+        description: Human-readable name of the configuration
+        example: "Content Groups"
+      scheme:
+        type: string
+        enum:
+          - cohort
+        description: Partition scheme (always 'cohort' for content groups)
+      description:
+        type: string
+        description: Detailed description of how this group is used
+        example: "The groups in this configuration can be mapped to cohorts in the Instructor Dashboard."
+      groups:
+        type: array
+        description: List of groups (cohorts) in this configuration
+        items:
+          $ref: '#/definitions/Group'
+      active:
+        type: boolean
+        description: Whether this configuration is active
+        example: true
+      version:
+        type: integer
+        description: Configuration version number (always 3 for current UserPartition format)
+        example: 3
+      parameters:
+        type: object
+        description: Additional partition parameters (usually empty for cohort scheme)
+        example: {}
+      read_only:
+        type: boolean
+        description: Whether this configuration is read-only (system-managed)
+        example: false
+
+  Group:
+    type: object
+    description: A single group (cohort) within a content group configuration
+    required:
+      - id
+      - name
+      - version
+      - usage
+    properties:
+      id:
+        type: integer
+        description: Unique identifier for this group within the configuration
+        example: 1
+      name:
+        type: string
+        description: Human-readable name of the group
+        example: "Content Group A"
+      version:
+        type: integer
+        description: Group version number (always 1 for current Group format)
+        example: 1
+      usage:
+        type: array
+        description: List of course units using this group for content restriction
+        items:
+          type: string
+        example: []
+
+  ErrorResponse:
+    type: object
+    description: Standard error response
+    required:
+      - error
+    properties:
+      error:
+        type: string
+        description: Human-readable error message
+      error_code:
+        type: string
+        description: Machine-readable error code (optional)
+      details:
+        type: object
+        description: Additional error details (optional)