Skip to content

feat: standardize Certificates API, add v2 (FC-0118 #39062) - #39316

Open
Faraz32123 wants to merge 4 commits into
masterfrom
feat/apply-fc-0118-adrs-to-certificates
Open

Faraz32123 wants to merge 4 commits into
masterfrom
feat/apply-fc-0118-adrs-to-certificates

Conversation

@Faraz32123

Copy link
Copy Markdown
Contributor

Summary

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.

Why a new version, not an in-place edit. The successor changes the contract for existing consumers: the error body becomes the standard envelope instead of {developer_message, error_code} (the v1 tests pin the old text), Bearer tokens and inactive-account sessions are no longer accepted (platform default authentication), a caller without access to a course that does not exist gets 403 instead of 404, Org/Course/Run keys no longer route, and the schema now says course_number_override may be null. The same move was made for textbooks and video settings in #39157.

Two additions beyond the issue table, both in the shared schema hook list: the v1 textbooks and v1 videos reads, superseded by #39157 but not marked there, are marked deprecated: true here.

Differences a v1 caller sees (the intentional list)

  1. Address: /api/authoring/v2/courses/{course_key}/certificate_settings/, trailing slash, parameter course_key.
  2. Errors use the standard envelope.
  3. Bearer tokens and inactive-user sessions are refused (401).
  4. A caller without access to a missing course gets 403, not 404. Permission is checked before the course is looked up.
  5. Deprecated Org/Course/Run keys and version-only keys do not route to a body (Org/Course/Run: HTML 404 from the converter; version-only key: JSON 404 from the permission class).
  6. course_number_override is published nullable (v1 already returned null when the course stores null, while its schema said string).
  7. A stored certificate or signatory missing a declared field is served with null (false for a missing active flag, empty list for missing signatories) instead of failing with a 500 as v1 does.

Everything else in the 200 body is identical, pinned by full-dict parity tests.

Change table

Commit Endpoint(s) Legacy behaviour kept New behaviour
Service, serializers, view, URL GET /api/authoring/v2/courses/{course_key}/certificate_settings/ v1 route, name cms.djangoapps.contentstore:v1:certificates, body and v1 operationId unchanged Plain ViewSet over a service that reuses get_certificates_context; can_manage computed in the service; new CanViewCertificates permission class; standard errors; platform default authentication
Schema hook v1 certificates, textbooks, videos reads Routes unchanged Added to SUPERSEDED_PATHS so the published schema marks them deprecated: true

ADRs applied

  • 0025 serializers — three new serializers with help_text on every field and explicit Meta.ref_name; serializer_class on the viewset
  • 0026 permissions — IsAuthenticated plus new CanViewCertificates; every legacy check is kept (see Authorization)
  • 0027 schema / docs — @extend_schema with 200/401/403/404, errors reference ErrorResponse, SDK tag on the viewset
  • 0028 viewsets — plain ViewSet (data comes from the modulestore), wired with path() and as_view({"get": "retrieve"}) like every authoring URLconf, because a router cannot express the nested singleton with the key converter
  • 0029 errors — StandardizedErrorMixin first in the MRO; only built-in error types; constant 404 text
  • 0030 GET idempotence — runtime SQL and signal capture, AuthZ off and on, GET and HEAD
  • 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
  • 0034 authentication — no authentication_classes line; platform default applies
  • 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
  • 0038 URL structure — courses/<course_key:course_key>/certificate_settings/, name course_certificate_settings, converter 404s and slashless redirect pinned
  • OEP-66 queryset scoping — n/a: no get_queryset for the mixin to wrap; access is decided per course by the permission class
  • OEP-69 conventions — hygiene gate, no governance text in code or schema

Compliance matrix

Decision Status How it is met, or the concrete reason it is excluded Evidence
0025 Met CertificateSettingsSerializer, ConfiguredCertificateSerializer, ConfiguredCertificateSignatorySerializer, ref names CertificateSettings, ConfiguredCertificate, ConfiguredCertificateSignatory; none collides with the v1 names or the three existing Certificate serializers. course_number_override is allow_null. Stored records missing a field are served with null CourseCertificateSettingsSchemaTest::test_every_serializer_field_documents_itself, ::test_nullable_fields_are_published_as_nullable, CourseCertificateSettingsIncompleteRecordTest; hygiene H9 PASS
0026 Met permission_classes = (IsAuthenticated, CanViewCertificates); same engine call and arguments as the legacy inline check CourseCertificateSettingsAccessTest (deny: anonymous, no role, other-course staff and instructor, limited staff, CCX); CourseCertificateSettingsAuthzEnabledTest (deny: no role, other-course policy role, limited staff); hygiene H7 PASS
0027 Met Summary, description, 200/401/403/404, SDK tag; operationId v2_courses_certificate_settings_retrieve CourseCertificateSettingsSchemaTest; schema_diff.py check-present --prefix /api/authoring/v2/ PASS
0028 Met Plain ViewSet + service, explicit path() CourseCertificateSettingsUrlTest::test_the_address_is_routed_to_the_retrieve_action_only; CourseCertificateSettingsQueryCountTest (19 queries on v1, 19 on v2)
0029 Met Standard envelope on 401, 403, 404, 405, 406, 500; 404 text is a constant; the 500 body carries no exception text assert_error_envelope in the access, authz, URL and CourseCertificateSettingsFailureTest tests
0030 Met No writes, no signals, CourseOverview never saved or loaded through get_from_id; one documented non-domain write: the authorization engine's cache-version row on a database's first role lookup, the same on v1 CourseCertificateSettingsReadOnlyTest, CourseCertificateSettingsReadOnlyAuthzEnabledTest, AuthorizationCacheInitialisationTest
0031 Excluded One read endpoint; no same-resource sibling in the pass n/a
0032 Excluded Singleton n/a
0033 Excluded No query parameters CourseCertificateSettingsParityTest::test_the_query_string_does_not_change_the_body
0034 Met No authentication_classes; platform default (JWT, session) test_a_bearer_token_is_not_accepted, test_an_inactive_course_author_is_not_authenticated, test_a_jwt_caller_is_served; hygiene H4 PASS
0035 Excluded Not front-end configuration n/a
0036 Excluded Flat singleton n/a
0037 Met (one deviation: no docstring marker — FC-0118 review, OEP-21 timing) New v2 module; check_old_versions_untouched.sh PASS with the protected legacy files; v1 marked deprecated: true only through SUPERSEDED_PATHS; the superseded view carries no docstring notice per FC-0118 review direction and OEP-21 (marker added only at Plan Accepted) versions gate; CourseCertificateSettingsSchemaTest::test_the_legacy_operation_keeps_its_id_and_is_marked_deprecated; cms/lib/tests/test_spectacular.py
0038 Met Converter route; name course_certificate_settings; legacy name untouched, so no alias is needed CourseCertificateSettingsUrlTest; url_snapshot.py check PASS
OEP-66 Excluded No get_queryset to wrap n/a
OEP-69 Met Hygiene gate (H1, H2, H4, H6, H7, H8, H9, H10, H11) gate output below

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.

In-place edits

File Category Evidence
cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py Current version extended with a new resource; one path() added url gate: no address or name removed
cms/djangoapps/contentstore/views/permissions.py Unversioned shared module; additive new CanViewCertificates. One existing import line is reflowed to add the new permission constant; one constant and one NotFound import are added legacy and v1 certificate tests unchanged and green
cms/lib/spectacular.py Three entries added to SUPERSEDED_PATHS schema_diff.py compare: exactly the three v1 reads newly deprecated
cms/lib/tests/test_spectacular.py Exact-set assertion updated; cases added that the new v2 paths and an unrelated v1 path are left unmarked red before the SUPERSEDED_PATHS edit, green after (mutation check)
cms/djangoapps/contentstore/rest_api/v2/views/tests/test_textbooks.py, .../test_video_settings.py Two schema assertions that the v1 textbooks and videos operations carry no deprecated flag now assert that they do these were the only tests that contradicted marking the two v1 reads

The superseded views carry no deprecation notice and are not in the diff.

Error-format decision

Versioned. v1 keeps {developer_message, error_code?}, which its tests pin; v2 answers the standard envelope. A search of frontend-app-authoring src/certificates and the end-to-end suite found no reader of developer_message; GitHub code search is not exhaustive, which is why v1 is not changed in place.

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.

Authorization

Legacy check Replaced by Notes
@view_auth_classes(is_authenticated=True) IsAuthenticated Anonymous: 401 authn
Inline user_has_course_permission(COURSES_VIEW_CERTIFICATES, READ) then permission_denied CanViewCertificates Same engine call and arguments, so AuthZ-on, AuthZ-off and CCX behaviour is unchanged. Returns False when the path has no course_key; answers 404 for a version-only key, on which the lookup would otherwise raise
can_manage = user_has_course_permission(COURSES_MANAGE_CERTIFICATES, WRITE) (not a gate) can_manage_certificates() in the service Informational field only
@verify_course_exists() ran before the permission check Converter 404 for malformed keys; NotFound from the service after the permission check Order flips on purpose: no existence oracle for callers without access

Deny-path tests: anonymous 401; no role, staff of another course, instructor of another course, limited staff, CCX course (even global staff) 403; no-role caller on a missing course 403 (the legacy route answers 404, asserted as the known difference); Bearer 401; inactive session 401; AuthZ on: no role, a policy role on another course and limited staff 403, COURSE_EDITOR and COURSE_AUDITOR 200 with can_manage false, COURSE_STAFF 200 with can_manage true.

Gate report

  • check_code_hygiene.py --base origin/master: PASS (0 FAIL, 0 WARN).
  • check_old_versions_untouched.sh with the protected legacy files and --allow for authoring_urls.py: PASS.
  • schema_diff.py compare / check-present --prefix /api/authoring/v2/: PASS.
  • url_snapshot.py check: PASS.
  • Tests: 276 passed, 0 failed (test_certificates.py 89, test_spectacular.py 23, legacy views/tests/test_certificates.py + rest_api/v1/views/tests/ 50, test_textbooks.py + test_video_settings.py 114). Query count: v1 19, v2 19.
  • SKIPPED: old-tests gate (explicit v1-only pytest invocation): v1 tests are part of the 276 and passed unmodified but were not run in a separate command. SKIPPED: V7 CERTIFICATES_HTML_VIEW=false with a real URLconf: not run; the stubbed NoReverseMatch test covers the 500 path.

What the gates do not show: H8 only greps method bodies and cannot see the service module, so idempotence rests on the runtime SQL and signal capture; the schema gate cannot see /api-docs/ (drf-yasg), where the explicit ref_name values matter.

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.

🤖 Generated with Claude Code

@Faraz32123 Faraz32123 self-assigned this Oct 27, 2026
@Faraz32123 Faraz32123 linked an issue Oct 27, 2026 that may be closed by this pull request
Faraz32123 added a commit that referenced this pull request Oct 28, 2026
Two changes requested by taimoor-ahmed-1 on #39316:

1. Remove resolve_course_key from the service. The path converter already
   parses the key, CanViewCertificates handles version-only keys, and
   get_course() is None gives the constant message. This aligns with the
   sibling textbooks and video_settings services, removes a v2→v3 import,
   and drops one redundant CourseOverview.course_exists query (v2 now 18,
   v1 still 19).

2. Declare authentication_classes = (JwtAuthentication,
   SessionAuthenticationAllowInactiveUser) to match the v2 neighbours from
   #39157. The legacy @view_auth_classes decorator included
   AllowInactiveUser; ADR 0034's migration rule says "remove Bearer only",
   so the remaining tuple is a justified deviation from the platform default.
   Without it, an inactive course author's certificates page would 401 while
   textbooks and video settings return 200.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Abdul-Muqadim-Arbisoft added a commit to edly-io/edx-platform that referenced this pull request Nov 4, 2026
This branch renamed openedx#39157's schema test and pinned the legacy
GET /api/contentstore/v1/videos/{course_id} as never deprecated, but
that listing has a successor of its own (video_settings), and openedx#39316
marks it. The test is back to openedx#39157's form, less the loop asserting
that the usage and download operations beside the listing are not
deprecated, which this branch makes false; its own contract tests
assert that they are.

The SUPERSEDED_PATHS comment and the test_spectacular.py rename now
match openedx#39316 word for word, so the two branches overlap only in the
list entries.

Part of openedx#39071.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Abdul-Muqadim-Arbisoft added a commit to edly-io/edx-platform that referenced this pull request Nov 4, 2026
Authentication: both views took the platform default, so an inactive
account was refused over a session but admitted with a JWT, which does
not check is_active; v1 admitted it either way through
@view_auth_classes(), and video_settings and textbooks on the same
mount declare (JwtAuthentication, SessionAuthenticationAllowInactiveUser).
Both views now declare the same pair, with a comment. An inactive
course author is still refused by the role check.

Version-only course keys: the course_key converter admits keys such as
course-v1:version@<id>, on which Studio's role check raises. The guard
that answered them with 404 lived in a separate HasFullCourseKey that
every view on the converter had to remember to list, and
video_settings did not, so it still answered 500. The guard now lives
in HasStudioReadAccess itself and HasFullCourseKey is gone, so
video_settings answers 404 as well.

Not-found detail: video_settings, textbooks and openedx#39316 say "The
requested course does not exist."; this branch said "The course does
not exist." and "Not found.". Both cases now use one
COURSE_NOT_FOUND_MESSAGE.

The contract tests stop reading the deployment settings in a
subprocess: since openedx#39300 the test settings carry the same schema
settings, so they use the shared generate_cms_schema() helper. Checks
that cms/lib/tests/test_spectacular.py already makes (the filter, the
registered hooks, the servers) are dropped, the operationId collision
check is narrowed to this branch's two ids, and the listing that has a
successor of its own is no longer pinned as unmarked. /api-docs/ runs
the same post-processing hooks, so it now marks the two v1 operations
deprecated too, and a test pins that.

Part of openedx#39071.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Faraz32123 added a commit that referenced this pull request Nov 10, 2026
Two changes requested by taimoor-ahmed-1 on #39316:

1. Remove resolve_course_key from the service. The path converter already
   parses the key, CanViewCertificates handles version-only keys, and
   get_course() is None gives the constant message. This aligns with the
   sibling textbooks and video_settings services, removes a v2→v3 import,
   and drops one redundant CourseOverview.course_exists query (v2 now 18,
   v1 still 19).

2. Declare authentication_classes = (JwtAuthentication,
   SessionAuthenticationAllowInactiveUser) to match the v2 neighbours from
   #39157. The legacy @view_auth_classes decorator included
   AllowInactiveUser; ADR 0034's migration rule says "remove Bearer only",
   so the remaining tuple is a justified deviation from the platform default.
   Without it, an inactive course author's certificates page would 401 while
   textbooks and video settings return 200.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
@Faraz32123
Faraz32123 force-pushed the feat/apply-fc-0118-adrs-to-certificates branch from 20f9551 to f9de444 Compare November 10, 2026 11:01
@Faraz32123
Faraz32123 marked this pull request as ready for review November 10, 2026 11:01
Faraz32123 and others added 4 commits November 13, 2026 12:39
Add a conforming v2 read at /api/authoring/v2/courses/{course_key}/certificate_settings/
that supersedes GET /api/contentstore/v1/certificates/{course_id}.

The new version is required because the contract changes for existing callers:
standard error envelope replaces {developer_message, error_code}; Bearer tokens
and inactive-account sessions are refused (platform default authentication);
permission is checked before existence (403 instead of 404 for missing courses
when the caller lacks access); course_number_override is published nullable;
and stored records missing a field are served tolerantly instead of failing
with a 500.

The v1 route, view, serializer, tests and URL name are untouched (zero-line
diff). The v1 certificates, textbooks and videos reads are marked
deprecated: true in the schema via SUPERSEDED_PATHS.

Service layer reuses get_certificates_context from the legacy view.
CanViewCertificates permission class uses the same engine call as the v1
inline check. StandardizedErrorMixin produces the standard envelope.
89 new tests: deny-path matrix, full-dict v2/v1 parity, query-count parity
(19 each), GET idempotence via SQL/signal capture, schema and URL contract.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Two changes requested by taimoor-ahmed-1 on #39316:

1. Remove resolve_course_key from the service. The path converter already
   parses the key, CanViewCertificates handles version-only keys, and
   get_course() is None gives the constant message. This aligns with the
   sibling textbooks and video_settings services, removes a v2→v3 import,
   and drops one redundant CourseOverview.course_exists query (v2 now 18,
   v1 still 19).

2. Declare authentication_classes = (JwtAuthentication,
   SessionAuthenticationAllowInactiveUser) to match the v2 neighbours from
   #39157. The legacy @view_auth_classes decorator included
   AllowInactiveUser; ADR 0034's migration rule says "remove Bearer only",
   so the remaining tuple is a justified deviation from the platform default.
   Without it, an inactive course author's certificates page would 401 while
   textbooks and video settings return 200.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The inactive-user test expected 200, but CourseStaffRole.has_user()
checks is_active and denies permission — the correct status is 403
(authenticated via SessionAuthenticationAllowInactiveUser, denied by
the role check).  The v2 query count dropped from 19 to 17 (not 18)
after removing resolve_course_key, which saved two DB round-trips
rather than one.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The case with a course mode (3 certs, 1 mode) runs 18 v2 queries, not
17 — the mode lookup adds one query over the zero-mode cases.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[API] Certificates

2 participants