feat: apply FC-0118 ADRs to youtube transcripts APIs

[Faraz32123]

Related Issue: #39061

Standardizes the two v0 YouTube transcript endpoints (YoutubeTranscriptCheckView, YoutubeTranscriptUploadView in cms/djangoapps/contentstore/rest_api/v0/views/transcripts.py) onto a new, additive v1 surface. v0 is untouched — every existing address still resolves to the same view with the same body; the two v0 operations are marked deprecated in the schema by a post-processing hook, not in code.

Only the two endpoints listed in #39061 are migrated. The sibling TranscriptView (/video_transcripts/...) is a different resource and is out of scope.

New addresses

Legacy (unchanged, now deprecated in the schema)	New
GET /api/contentstore/v0/youtube_transcripts/{course_id}/check	GET /api/authoring/v1/courses/{course_key}/youtube_transcript_checks/
GET /api/contentstore/v0/youtube_transcripts/{course_id}/upload	POST /api/authoring/v1/courses/{course_key}/youtube_transcript_imports/

Two changes worth calling out

The import endpoint becomes a POST. The legacy GET .../upload performs four domain writes — an outbound YouTube download, create_external_video (not idempotent), create_or_update_video_transcript, and video.save(). That is the GET-mutates violation ADR 0030 targets. The new endpoint is a POST; the frozen v0 GET keeps all four writes exactly as today, so nothing is taken away from existing callers.

The legacy URL regexes truncate, and that is preserved. ^youtube_transcripts/{COURSE_ID_PATTERN}/check?$ makes the final character optional, so reverse() actually emits /chec, and all four spellings resolve today: /chec, /check, /uploa, /upload. This PR does not touch v0/urls.py at all, so all four keep resolving to their original views. /check/ keeps 404ing, as it does now. Verified by direct resolve() assertions and by a URL-snapshot diff of all 2181 base routes.

ADR compliance

ADR	Status	Notes
0025 Serializers	Applied	Five serializers, help_text on every field. Responses are serializer-produced; requests are validated before the legacy call. Two field/reality fixes adopted: current_item_subs is a string-or-null (v0 declared ListField), and edx_video_id is nullable — None is a legitimate success value for V2 libraries. Neither changes a wire value: the v0 serializers were declared but never instantiated.
0026 Permissions	Applied	permission_classes = (IsAuthenticated, HasCourseAuthorAccess) on each viewset, reusing the existing class. All three legacy authorization layers survive.
0027 Schema	Applied	@extend_schema per action, tags=["openedx-platform-sdk"] on both, every 4xx documented with ErrorResponseSerializer.
0028 Views	Applied	Plain viewsets.ViewSet — the data path is modulestore/contentstore/edxval plus an outbound HTTP call, not an ORM queryset, so ModelViewSet does not apply. Both actions delegate to the existing legacy functions unchanged, so no new N+1s; a query-count test pins this against the legacy address.
0029 Errors	Applied	StandardizedErrorMixin first in the MRO. Django-native PermissionDenied and Http404/ItemNotFoundError are translated to their DRF equivalents at the service boundary — without that, a denied caller would be reported as internal/500 rather than authz/403. No error types are registered: the registry is process-wide, so a 405 or a malformed body keeps the library's current classification until edx-drf-extensions covers them, as in #39102. A missing youtube entry in the import's videos is reported on videos. Error text is fixed and generic; the upstream exception message is logged server-side, never returned.
0030 GET side effects	Applied	See above. The new GET is proven write-free by runtime SQL capture, not by static inspection — a hygiene check cannot see a write one frame down.
0031 Merges	Applied as a reasoned non-merge	Same resource domain, but they differ in side effects, HTTP semantics and response shape, so the ADR's two-part test fails. Merging would force a safe read through a write-shaped entry point and re-commit the 0030 violation. They are consolidated onto one URLconf and one service module instead.
0032 Pagination	Not applicable	Neither endpoint returns a collection — each returns a single object (9 fields and 2 fields). There is no list to bound.
0033 Filtering	Not applicable	No list, so nothing to filter or order. The one input parameter identifies which block is addressed; it is an identifier payload, not a filter, and varying it cannot widen what the caller may see.
0034 Authentication	Applied	BearerAuthenticationAllowInactiveUser dropped. (JwtAuthentication, SessionAuthenticationAllowInactiveUser) is a documented deviation from the default pair, commented at the declaration: inactive Studio authors reach this from the authoring UI today, and the default session class would refuse callers v0 accepts.
0035 MFE config	Not applicable	Neither endpoint returns site or front-end configuration. Both are authenticated, per-course, per-block authoring operations.
0036 Nested JSON	Not applicable	Both responses are flat sets of thin scalars with no sub-objects or tree shape, which the ADR excludes by its own terms.
0037 Versioning	Applied, except the DEPR link	New version; v0 frozen; all four live spellings preserved. The v0 operations are marked deprecated: true in the schema by a post-processing hook; the v0 code is unchanged. The deprecation is being recorded as a row on the existing DEPR issue #39128 rather than a new one. Removal window: one named release after Verawood.
0038 URLs	Applied	Verbs removed from the path (check/upload become the noun collections youtube_transcript_checks/youtube_transcript_imports); one level of nesting under courses/; course key via path converter, so a malformed key is a routing-level 404; mandatory trailing slash; version-free URL names. api_name is authoring, not contentstore — the ADR's Rejected Alternatives names URLs mirroring the codebase as publishing an implementation detail as a public contract.
OEP-66 Scoping	Not applicable as a mechanism	Neither view has a get_queryset() for ScopedQuerysetMixin to wrap. The three layers are still present: endpoint access via permission classes, record visibility via the course key plus the item's own course-key re-check, and user input applied strictly after both.

Compatibility evidence

• URL gate: 0 FAIL / 0 WARN. Head 2183 routes vs base 2181 — the only difference is the two new routes. Every base address still resolves.
• All four live v0 spellings assert-tested to resolve to their original views; the legacy URL names still reverse.
• Legacy tests pass unmodified: cms/djangoapps/contentstore/views/tests/test_transcripts.py, 44 passed, file untouched in this diff.
• v0/urls.py and cms/djangoapps/contentstore/views/transcripts_ajax.py are not modified. The latter matters because the one real frontend consumer (frontend-app-authoring) calls the legacy non-REST Studio routes that share it.
• Consumer search across the openedx org found no external caller of either REST path.
• 80 new tests, including a full deny matrix (anonymous → 401 authn; student and other-course instructor → 403 authz; instructor and staff → 200), a cross-course locator refusal on both endpoints asserting the slug is authz and not internal, and tests proving the course-level permission fires before the item is loaded.

Files changed outside the v1 package, and why

File	Why
cms/urls.py	Mounts api/authoring/v1/ after the existing contentstore include, and calls register_url_converters() before the first pattern using a converter. Additive only.
cms/lib/spectacular.py	The filter admits only ^/api/contentstore/v\d+/, so the new endpoints would route and test green but be silently absent from the published schema. Widened to ^/api/(contentstore|authoring)/v\d+/, plus a post-processing hook marking the v0 paths deprecated — done here rather than in the v0 files, which are frozen.
cms/envs/common.py, cms/envs/devstack.py, cms/envs/production.py	Register the post-processing hook (restating postprocess_schema_enums, since setting the key replaces drf-spectacular's defaults), and remove SCHEMA_PATH_PREFIX_TRIM so paths publish at their full address instead of mixing prefixes.

Gate results

versions        PASS   (allowlisted files justified above)
hygiene         PASS   0 FAIL / 0 WARN, 13 files
urls            PASS   0 FAIL / 0 WARN, 2181 base routes preserved
schema present  PASS   both endpoints published, no mixed-prefix warning
old tests       PASS   44 legacy tests green, file unmodified
new tests       PASS   80
ruff            PASS
schema compare  FAIL   — expected; see below

On the schema-compare failure. Removing SCHEMA_PATH_PREFIX_TRIM re-keys every existing path from its trimmed form (/v0/...) to its full address (/api/contentstore/v0/...). The differ sees 56 removals and 56 additions as unrelated and reports them as breaking. Reconciled mechanically instead:

• base 57 paths → head 59 paths;
• 0 removed paths fail to reappear at their full address;
• 2 genuinely new paths — the two /api/authoring/v1/ endpoints;
• exactly 2 operations differ in any key across the entire schema — the two v0 YouTube operations, each gaining deprecated: true. No other operation changed.

Reverting the trim removal would turn this gate green and leave the schema publishing a mix of trimmed and untrimmed paths that no single server URL serves.

Known gaps

• A routing-level 404 on the new mount (malformed course key) is answered with HTML by the CMS handler404, not JSON. A test pins the current behaviour so it is visible rather than hidden. Fixing it needs a catch-all route, which other in-flight PRs are adding.
• cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py is also added by feat: apply ADR 0038 (URL structure standardization) across 6 standardized APIs #39078 and feat: standardize Course Videos API into authoring v1 #39102. All three are additive router registrations; the merge resolution is to keep all of them.