Skip to content

[API] Container Management #39064

Open

Description

@FuaadZam

Functional Area: Container Management

Endpoints under this functional area:

Module API Version Resource / Endpoint HTTP Method Description
Container Handler v1 /contentstore/v1/container_handler/{usage_key_string} GET Retrieves detailed vertical container data for a given usage_key_string. Returns a JSON object including display name, type, category, position, collapsible state, URLs for previous/next units, draft and published preview links, course sequence IDs, ancestor xblocks with children, component templates, xblock info, user clipboard content, and flags like is_unit_page and is_fullwidth_content. Supports AI tools in rendering course content dynamically, navigating course structure, and automating content analysis. Path parameter usage_key_string is required.

Activity

  1. added theissue type on Sep 2, 2026
  2. taimoor-ahmed-1 commented on Oct 22, 2026

    @taimoor-ahmed-1
    Contributor

    Standardization PR open: #39274

    PR: #39274 — feat: serve course containers from authoring v2
    State: open

    What this does

    Standardizes the Container Management area (#39064, part of #38137). The area has one endpoint, the Unit page read GET /api/contentstore/v1/container_handler/{usage_key_string}. This PR adds its successor:

    ADRs applied

    7 of 16 decisions applied on this pass; every one left open carries its reason.

    • 0025 serializers
    • 0026 permissions
    • 0027 schema / docs
    • 0034 authentication
    • 0036 nested JSON
    • 0038 URL structure
    • OEP-69 conventions
    • 0028 viewsets — applied except router registration: a ViewSet backed by a service module, mounted with path(...) and the shared usage_key converter rather than a DRF Router, as every route in authoring_urls.py is
    • 0029 errors — partial: the envelope on every response this view produces, but two library and platform gaps remain and are pinned by tests: a malformed or i4x:// key gets the CMS HTML 404 at routing, and 405/406 are typed internal
    • 0030 GET idempotence — met for this code (no clipboard read, nothing written or signalled on GET or HEAD), with one inherited write outside it: openedx-authz inserts its PolicyCacheControl row on the first permission check against a database that lacks it, as on v1 and feat: serve the course outline from authoring v2 #39229
    • 0031 merged endpoints — n/a: one read operation; the v1 children route is a different representation, owned by [API] Containers #39063
    • 0032 pagination — n/a: a single resource; the default view has no unbounded list, and the view=full lists are the opt-in Unit page payload
    • 0033 filtering — n/a: no list; the only parameter, view, selects a representation and is validated with an enum
    • 0035 MFE config — n/a: per-container course-authoring data, not site or front-end configuration
    • 0037 versioning — partial: v2 module, v1 frozen (docstring-only marker) and deprecated: true in the schema; the DEPR entry is a comment on [DEPR]: Contentstore and enrollment API versions superseded by FC-0118 #39128 until it is folded into the issue body
    • OEP-66 queryset scoping — n/a as a mechanism: not a list, and the data comes from the modulestore with no get_queryset(); the layering is in the matrix

    The evidence for each tick is the compliance matrix in the PR body; nothing is ticked without a named test or gate line.

    Backward compatibility

    • v1 is unchanged. vertical_block.py gains docstring text only. Its syntax tree with docstrings stripped equals the base. The v1 route, view and URL name cms.djangoapps.contentstore:v1:container_handler are untouched, and v1's error body is pinned (ContainerRoutingTest::test_v1_keeps_its_own_error_body).
    • Legacy tests are not edited. rest_api/v1/views/tests/test_vertical_block.py is not in the diff.
    • Parity. view=full is compared with v1 field by field, through the Django test client, for every member that has a Unit page, and for each of these cases:
      • neighbours across subsections and sections, and across a section with no units;
      • containers inside a unit, and containers that declare their block types;
      • the course's component templates and configured support levels;
      • the library content picker on and off, and tagging on and off;
      • public video sharing on and off;
      • preview links with and without an LMS address;
      • keys pinned to the draft branch and to a course version;
      • a child that cannot be loaded before the unit (position is counted as v1 counts it).

    Gates

    Gate report (step 7) — 2026-10-22 16:07 — base 53ea5f4 (#39229 head; stacked)

    versions

    ALLOWED M cms/djangoapps/contentstore/rest_api/v1/views/vertical_block.py matches --allow 'cms/djangoapps/contentstore/rest_api/v1/views/vertical_block.py'
    ALLOWED M cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py matches --allow 'cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py'
    ADDED A cms/djangoapps/contentstore/rest_api/v2/container_service.py new file inside pre-existing cms/djangoapps/contentstore/rest_api/v2/ (justify in PR body: dual mount / new test module)
    ADDED A cms/djangoapps/contentstore/rest_api/v2/serializers/containers.py new file inside pre-existing cms/djangoapps/contentstore/rest_api/v2/ (justify in PR body: dual mount / new test module)
    ADDED A cms/djangoapps/contentstore/rest_api/v2/views/containers.py new file inside pre-existing cms/djangoapps/contentstore/rest_api/v2/ (justify in PR body: dual mount / new test module)
    ALLOWED M cms/djangoapps/contentstore/rest_api/v2/views/tests/helpers.py matches --allow 'cms/djangoapps/contentstore/rest_api/v2/views/tests/helpers.py' OLD TEST CHANGED — behaviour changed
    ADDED A cms/djangoapps/contentstore/rest_api/v2/views/tests/test_containers.py new file inside pre-existing cms/djangoapps/contentstore/rest_api/v2/ (justify in PR body: dual mount / new test module)
    ALLOWED M cms/djangoapps/contentstore/rest_api/v2/views/tests/test_course_outline.py matches --allow 'cms/djangoapps/contentstore/rest_api/v2/views/tests/test_course_outline.py' OLD TEST CHANGED — behaviour changed
    files in new version dirs: 0 other files: 3 added in old dirs: 4 allowed: 4
    RESULT: PASS

    hygiene

    Hygiene gate — 11 file(s) scanned (added lines vs 53ea5f4)
    RESULT: PASS (0 FAIL, 0 WARN)

    ruff

    All checks passed!

    schema: SKIPPED (no platform environment)

    urls: SKIPPED (no platform environment)

    old-tests: SKIPPED (no platform environment)

    tests: SKIPPED (no platform environment)

    supplementary (not a gate): fake-modulestore differential harness 147 PASS / 0 FAIL

    Deprecations

    GET /api/contentstore/v1/container_handler/{usage_key_string} is superseded by GET /api/authoring/v2/containers/{usage_key}/?view=full. It is deprecated: true in the CMS schema and its docstrings name the successor. The view is otherwise unchanged: no runtime header. Tracked on the FC-0118 umbrella DEPR ticket, #39128; this area's entry is posted there with the PR. Window per #39128: removed one named release after the release this ships in.

    Migration notes for callers:

    • Call /api/authoring/v2/containers/{usage_key}/?view=full, with the trailing slash.
    • Read the clipboard from /api/content-staging/v1/clipboard/ (the authoring MFE already does).
    • action is gone.
    • Errors use the standard envelope.
    • Bearer tokens are refused; use JWT or a session. A session-only call by an inactive user is refused.
    • A leaf component key is a 404: use /api/authoring/v1/xblocks/{usage_key}/ for component data. Library and i4x:// keys are 404.

    Follow-ups

    • SDK: the operation carries openedx-platform-sdk, so the next openedx-platform-sdk regeneration gains v2_containers_retrieve.
    • frontend-app-authoring: src/course-unit/data/api.ts can move getVerticalData to /api/authoring/v2/containers/{usage_key}/?view=full.
    • [API] Containers #39063 (Containers): its children endpoint should mount at containers/{usage_key}/children/ under this member.
    • The clipboard endpoint writes on GET. /api/content-staging/v1/clipboard/ can save a CourseOverview row and send IMPORT_COURSE_DETAILS on read, as v1 container_handler did. Issue to be filed.
    • openedx-authz PolicyCacheControl. The first permission check on a fresh database inserts the cache row on a read. Seeding it by migration would make reads write-free. Issue to be filed.
    • JSON 404 for unmatched /api/ addresses. A platform-level fix (CMS handler404 answering with the envelope for /api/ paths) instead of per-area catch-alls. Issue to be filed.
    • edx-drf-extensions: catalogue MethodNotAllowed and NotAcceptable so 405/406 stop being typed internal. Issue to be filed.
    • Authentication consistency across /api/authoring/v2/: textbooks and video_settings keep SessionAuthenticationAllowInactiveUser; the outline and this view use the default. One policy for new versions of such endpoints should be agreed.

    Review on the PR, please — this issue stays open until it merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions