Repository navigation
feat: standardize Certificates API, add v2 (FC-0118 #39062) - #39316
Open
Faraz32123 wants to merge 4 commits into
Open
Faraz32123 wants to merge 4 commits into
Faraz32123 wants to merge 4 commits into
Conversation
This was referenced Oct 27, 2026
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]>
This was referenced Oct 31, 2026
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
force-pushed
the
feat/apply-fc-0118-adrs-to-certificates
branch
from
November 10, 2026 11:01
20f9551 to
f9de444
Compare
Faraz32123
marked this pull request as ready for review
November 10, 2026 11:01
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]>
Faraz32123
force-pushed
the
feat/apply-fc-0118-adrs-to-certificates
branch
from
November 13, 2026 07:50
f9de444 to
042c7f4
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 atGET /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/Runkeys no longer route, and the schema now sayscourse_number_overridemay benull. 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: truehere.Differences a v1 caller sees (the intentional list)
/api/authoring/v2/courses/{course_key}/certificate_settings/, trailing slash, parametercourse_key.Org/Course/Runkeys 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).course_number_overrideis published nullable (v1 already returnednullwhen the course storesnull, while its schema said string).null(falsefor 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
GET /api/authoring/v2/courses/{course_key}/certificate_settings/cms.djangoapps.contentstore:v1:certificates, body and v1 operationId unchangedViewSetover a service that reusesget_certificates_context;can_managecomputed in the service; newCanViewCertificatespermission class; standard errors; platform default authenticationSUPERSEDED_PATHSso the published schema marks themdeprecated: trueADRs applied
help_texton every field and explicitMeta.ref_name;serializer_classon the viewsetIsAuthenticatedplus newCanViewCertificates; every legacy check is kept (see Authorization)@extend_schemawith 200/401/403/404, errors referenceErrorResponse, SDK tag on the viewsetViewSet(data comes from the modulestore), wired withpath()andas_view({"get": "retrieve"})like every authoring URLconf, because a router cannot express the nested singleton with the key converterStandardizedErrorMixinfirst in the MRO; only built-in error types; constant 404 textcertificatesarray would change the contractauthentication_classesline; platform default appliesv2resource, v1 and the legacy Studio routes untouched, v1 marked deprecated only through the schema hookcourses/<course_key:course_key>/certificate_settings/, namecourse_certificate_settings, converter 404s and slashless redirect pinnedget_querysetfor the mixin to wrap; access is decided per course by the permission classCompliance matrix
CertificateSettingsSerializer,ConfiguredCertificateSerializer,ConfiguredCertificateSignatorySerializer, ref namesCertificateSettings,ConfiguredCertificate,ConfiguredCertificateSignatory; none collides with the v1 names or the three existingCertificateserializers.course_number_overrideisallow_null. Stored records missing a field are served withnullCourseCertificateSettingsSchemaTest::test_every_serializer_field_documents_itself,::test_nullable_fields_are_published_as_nullable,CourseCertificateSettingsIncompleteRecordTest; hygiene H9 PASSpermission_classes = (IsAuthenticated, CanViewCertificates); same engine call and arguments as the legacy inline checkCourseCertificateSettingsAccessTest(deny: anonymous, no role, other-course staff and instructor, limited staff, CCX);CourseCertificateSettingsAuthzEnabledTest(deny: no role, other-course policy role, limited staff); hygiene H7 PASSv2_courses_certificate_settings_retrieveCourseCertificateSettingsSchemaTest;schema_diff.py check-present --prefix /api/authoring/v2/PASSViewSet+ service, explicitpath()CourseCertificateSettingsUrlTest::test_the_address_is_routed_to_the_retrieve_action_only;CourseCertificateSettingsQueryCountTest(19 queries on v1, 19 on v2)assert_error_envelopein the access, authz, URL andCourseCertificateSettingsFailureTesttestsCourseOverviewnever saved or loaded throughget_from_id; one documented non-domain write: the authorization engine's cache-version row on a database's first role lookup, the same on v1CourseCertificateSettingsReadOnlyTest,CourseCertificateSettingsReadOnlyAuthzEnabledTest,AuthorizationCacheInitialisationTestCourseCertificateSettingsParityTest::test_the_query_string_does_not_change_the_bodyauthentication_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 PASSv2module;check_old_versions_untouched.shPASS with the protected legacy files; v1 markeddeprecated: trueonly throughSUPERSEDED_PATHS; the superseded view carries no docstring notice per FC-0118 review direction and OEP-21 (marker added only at Plan Accepted)CourseCertificateSettingsSchemaTest::test_the_legacy_operation_keeps_its_id_and_is_marked_deprecated;cms/lib/tests/test_spectacular.pycourse_certificate_settings; legacy name untouched, so no alias is neededCourseCertificateSettingsUrlTest;url_snapshot.py checkPASSget_querysetto wrapBackward compatibility
v1/mixins.py,views/certificates.py,views/certificate_manager.py,views/serializers.py,views/tests/test_certificates.pyandcms/urls.pyare not in the diff.url_snapshot.py checkPASS (0 FAIL, 0 WARN, no address or name removed). The legacy route resolves, including the deprecatedOrg/Course/Runkey (test_the_legacy_route_still_serves_a_deprecated_key).schema_diff.py comparePASS, 0 BREAKING, 0 WARN. Added: one operation, three components (CertificateSettings,ConfiguredCertificate,ConfiguredCertificateSignatory), one operationId. Newlydeprecated: the three v1 reads. No operationId, component or URL name removed.v2.data == v1.datafor course staff and global staff, no certificates, two certificates of two signatories, active certificate, with and without a certificate-awarding mode,LEGACY_STUDIO_EXAM_SETTINGSon and off with and without an authoring URL, a set and a nullcourse_number_override. The intentional differences are the list above.In-place edits
cms/djangoapps/contentstore/rest_api/v2/authoring_urls.pypath()addedcms/djangoapps/contentstore/views/permissions.pyCanViewCertificates. One existing import line is reflowed to add the new permission constant; one constant and oneNotFoundimport are addedcms/lib/spectacular.pySUPERSEDED_PATHSschema_diff.py compare: exactly the three v1 reads newly deprecatedcms/lib/tests/test_spectacular.pySUPERSEDED_PATHSedit, green after (mutation check)cms/djangoapps/contentstore/rest_api/v2/views/tests/test_textbooks.py,.../test_video_settings.pydeprecatedflag now assert that they doThe 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 offrontend-app-authoringsrc/certificatesand the end-to-end suite found no reader ofdeveloper_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 byGET /api/authoring/v2/courses/{course_key}/certificate_settings/and markeddeprecated: truein 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
@view_auth_classes(is_authenticated=True)IsAuthenticatedauthnuser_has_course_permission(COURSES_VIEW_CERTIFICATES, READ)thenpermission_deniedCanViewCertificatesFalsewhen the path has nocourse_key; answers 404 for a version-only key, on which the lookup would otherwise raisecan_manage = user_has_course_permission(COURSES_MANAGE_CERTIFICATES, WRITE)(not a gate)can_manage_certificates()in the service@verify_course_exists()ran before the permission checkNotFoundfrom the service after the permission checkDeny-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_managefalse, COURSE_STAFF 200 withcan_managetrue.Gate report
check_code_hygiene.py --base origin/master: PASS (0 FAIL, 0 WARN).check_old_versions_untouched.shwith the protected legacy files and--allowforauthoring_urls.py: PASS.schema_diff.py compare/check-present --prefix /api/authoring/v2/: PASS.url_snapshot.py check: PASS.test_certificates.py89,test_spectacular.py23, legacyviews/tests/test_certificates.py+rest_api/v1/views/tests/50,test_textbooks.py+test_video_settings.py114). Query count: v1 19, v2 19.CERTIFICATES_HTML_VIEW=falsewith a real URLconf: not run; the stubbedNoReverseMatchtest 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 explicitref_namevalues matter.Follow-ups
CERTIFICATES_HTML_VIEWis true (default false). With it false the read fails with a 500 on v1 and on v2, as the standardinternalenvelope on v2 (test_an_unrecoverable_failure_is_an_internal_error_with_a_generic_body).certificateslist ofnullstill fails with a 500 on both routes inside the shared context builder, which this pass does not edit.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).openedx-platform-sdk, so an SDK regeneration follows.🤖 Generated with Claude Code