Skip to content

[API] Certificates #39062

Open

Description

@FuaadZam

Functional Area: Certificates

Endpoints under this functional area:

Module API Version Resource / Endpoint HTTP Method Description
Course Management v1 /contentstore/v1/certificates/{course_id} GET Retrieves all certificates associated with a course, including certificate_activation_handler_url, certificate_web_view_url, certificates array with details (course_title, description, signatories, is_active, etc.), course_modes, and other metadata. Useful for AI tools performing automated certificate verification, reporting, or analytics.

Activity

  1. added theissue type on Sep 2, 2026
  2. Faraz32123 commented on Oct 27, 2026

    @Faraz32123
    Contributor

    Standardization PR open: #39316

    PR: #39316

    What this does

    Standardizes the course certificate configuration read, [API] Certificates (#39062), under FC-0118 (umbrella #38137). The one endpoint in the issue's table, GET /api/contentstore/v1/certificates/{course_id}, now has a conforming successor at GET /api/authoring/v2/courses/{course_key}/certificate_settings/. The v1 route, its view, serializer, tests and URL name are untouched (zero-line diff) and keep working.

    ADRs applied

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

    • 0025 serializers
    • 0026 permissions
    • 0027 schema / docs
    • 0028 viewsets
    • 0029 errors
    • 0030 GET idempotence
    • 0034 authentication
    • 0038 URL structure
    • OEP-69 conventions
    • 0031 merged endpoints — n/a: the area is one read endpoint with no same-resource sibling in this pass; the legacy certificate write routes are not in the issue's table and are a candidate for a follow-up
    • 0032 pagination — n/a: one object per course, not a list; paginating the embedded certificates array would change the contract
    • 0033 filtering — n/a: no query parameters are read; the only input is the path key
    • 0035 MFE config — n/a: an authenticated per-course resource, not front-end runtime configuration
    • 0036 nested JSON — n/a: flat singleton; the nested signatories are small stored records, nothing heavy to project
    • 0037 versioning — one recorded deviation: no docstring marker (FC-0118 review, OEP-21 timing); new v2 resource, v1 and the legacy Studio routes untouched, v1 marked deprecated only through the schema hook
    • OEP-66 queryset scoping — n/a: no get_queryset for the mixin to wrap; access is decided per course by the permission class

    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

    • Versions gate: PASS. The v1 certificates module, serializer, tests, v1/mixins.py, views/certificates.py, views/certificate_manager.py, views/serializers.py, views/tests/test_certificates.py and cms/urls.py are not in the diff.
    • URL gate: url_snapshot.py check PASS (0 FAIL, 0 WARN, no address or name removed). The legacy route resolves, including the deprecated Org/Course/Run key (test_the_legacy_route_still_serves_a_deprecated_key).
    • Schema gate: schema_diff.py compare PASS, 0 BREAKING, 0 WARN. Added: one operation, three components (CertificateSettings, ConfiguredCertificate, ConfiguredCertificateSignatory), one operationId. Newly deprecated: the three v1 reads. No operationId, component or URL name removed.
    • Legacy tests are unmodified and green: the v1 certificates view tests and the legacy Studio certificates tests (50 tests).
    • Query count: v1 19 queries, v2 19 queries, warm caches, 0 and 3 certificates and with a certificate-awarding mode.
    • Parity: v2.data == v1.data for course staff and global staff, no certificates, two certificates of two signatories, active certificate, with and without a certificate-awarding mode, LEGACY_STUDIO_EXAM_SETTINGS on and off with and without an authoring URL, a set and a null course_number_override. The intentional differences are the list above.

    Gates

    Gate report: Certificates v2 (#39062)

    Run 2026-10-27, branch feat/apply-fc-0118-adrs-to-certificates

    Base ref: origin/master (03698e2)

    Gates run by orchestrator (verified independently on worktree)

    === VERSIONS GATE ===
    ADR 0037 gate — base: origin/master (working tree)
    ALLOWED M cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py
    ALLOWED M cms/djangoapps/contentstore/rest_api/v2/views/tests/test_textbooks.py (OLD TEST CHANGED)
    ALLOWED M cms/djangoapps/contentstore/rest_api/v2/views/tests/test_video_settings.py (OLD TEST CHANGED)
    ADDED A cms/djangoapps/contentstore/rest_api/v2/certificates_service.py
    ADDED A cms/djangoapps/contentstore/rest_api/v2/serializers/certificates.py
    ADDED A cms/djangoapps/contentstore/rest_api/v2/views/certificates.py
    ADDED A cms/djangoapps/contentstore/rest_api/v2/views/tests/test_certificates.py
    files in new version dirs: 0 other files: 3 added in old dirs: 4 allowed: 3
    RESULT: PASS

    --allow justification for sibling test edits: the user directed that #39157's v1
    textbooks and videos be marked as superseded in this PR, which necessarily changes
    the v2 sibling tests that previously asserted v1 was NOT deprecated.

    === HYGIENE GATE ===
    Hygiene gate — 10 file(s) scanned (added lines vs origin/master)
    RESULT: PASS (0 FAIL, 0 WARN)

    Gates run by implementer (same code, same commit, throwaway container)

    Code has not changed between the implementer's run and this report.

    === SCHEMA COMPARE ===
    schema_diff.py compare (dev settings, base vs head dump)
    RESULT: PASS (0 BREAKING, 0 WARN, 6 INFO)
    INFO: 1 operation added (v2_courses_certificate_settings_retrieve)
    INFO: 3 components added (CertificateSettings, ConfiguredCertificate, ConfiguredCertificateSignatory)
    INFO: 1 operationId added
    INFO: 3 v1 reads newly deprecated (certificates, textbooks, videos)

    === SCHEMA CHECK-PRESENT ===
    schema_diff.py check-present --prefix /api/authoring/v2/
    RESULT: PASS (3 paths under /api/authoring/v2/)

    === URL SNAPSHOT ===
    url_snapshot.py check (base vs head)
    RESULT: PASS (0 FAIL, 0 WARN)
    0 ADDR removals, 0 NAME removals

    === TESTS ===
    pytest (cms.envs.test):
    test_certificates.py: 89 passed
    test_spectacular.py: 23 passed
    legacy views/tests/test_certificates.py: 50 passed (UNMODIFIED)
    rest_api/v1/views/tests/test_certificates.py: included in legacy count (UNMODIFIED)
    test_textbooks.py + test_video_settings.py: 114 passed
    TOTAL: 276 passed, 0 failed

    Query count: v1=19, v2=19 (parity)

    === RUFF / PYLINT ===
    ruff check: All checks passed
    pylint: no findings

    Django-dependent gates could not be re-run by orchestrator

    The Tutor dev container image (openedx-dev:23.0.0-main) has stale packages
    (openedx-filters 3.14.0 vs master's 3.16.0; missing openedx-learning.urls)
    that prevent running manage.py cms against master. The implementer resolved this
    by installing master-pinned packages in throwaway containers. The orchestrator
    verified the file-based gates (versions, hygiene) independently; the Django-dependent
    gates (schema, URLs, tests) were verified by the implementer on the same unchanged code.

    SKIPPED gates

    • old-tests gate (explicit pytest of v1 tests in isolation): v1 tests are part of the
      276 that passed, but were not run in a separate invocation.
    • V7 (CERTIFICATES_HTML_VIEW=false with a real URLconf): not run; the stubbed
      NoReverseMatch test covers the 500 path.

    Deprecations

    GET /api/contentstore/v1/certificates/{course_id} is superseded by GET /api/authoring/v2/courses/{course_key}/certificate_settings/ and marked deprecated: true in the published schema. The v1 textbooks (/api/contentstore/v1/textbooks/{course_id}) and videos (/api/contentstore/v1/videos/{course_id}) reads, superseded by the merged #39157, are marked the same way here because that change did not mark them. The superseded views are unchanged: no response header, and no deprecation notes in code.

    Tracked on the FC-0118 umbrella DEPR ticket, #39128, which removes them one named release after the release this ships in. This area's entry is posted there once the PR is open.

    Follow-ups

    • Known gap: malformed course keys answer the service's HTML 404, because no JSON catch-all exists under this mount.
    • Known gap, no owner yet, to be filed as an issue: the response embeds the addresses of two legacy Studio routes that exist only when CERTIFICATES_HTML_VIEW is true (default false). With it false the read fails with a 500 on v1 and on v2, as the standard internal envelope on v2 (test_an_unrecoverable_failure_is_an_internal_error_with_a_generic_body).
    • A stored certificates list of null still fails with a 500 on both routes inside the shared context builder, which this pass does not edit.
    • Next-version candidates: a courses/{course_key}/certificates/ collection for the legacy write routes; the default authentication classes have no schema extension, so the operation publishes no security scheme (drf-spectacular warns once per class).
    • SDK: the v2 operation is tagged openedx-platform-sdk, so an SDK regeneration follows.
    • The authoring MFE still calls v1 and moves to v2 separately.

    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

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions