[taimoor-ahmed-1]

Stacked on #39303 (advanced settings, which adds IsExistingCourse and the shared test helpers). Until #39303 merges this branch also carries its commits; only the last 7 commits belong to this PR.

Summary

Part of #39059

Standardizes the custom pages and tabs resources of the Course Management area (#39059, part of #38137). This is PR C of the eight resource-group PRs for the area; #39303 (advanced settings) is PR A.

Three conforming operations replace the three v0 tab endpoints:

v0 (unchanged, now deprecated: true)	v1	URL name (authoring_v1:)
GET /api/contentstore/v0/tabs/{course_id}	GET /api/authoring/v1/custom_pages/?course_key={course_key}	custom_page_list
POST /api/contentstore/v0/tabs/{course_id}/reorder	PUT /api/authoring/v1/courses/{course_key}/custom_page_order/	course_custom_page_order
POST /api/contentstore/v0/tabs/{course_id}/settings?tab_id=	PATCH /api/authoring/v1/courses/{course_key}/tabs/{tab_id}/	course_tab_detail

It applies ADRs 0025–0038 and OEP-69.

Two resources, not one. v0's "tabs" endpoints act on two different things. The list and the reorder only ever see custom pages (static tabs): v0's GET keeps only static_tab entries, and its reorder only moves static tabs. The settings endpoint only ever succeeds on built-in tabs (progress, dates, wiki and the like), because a static tab is never hideable (StaticTab keeps CourseTab.is_hideable = False). So v1 names them separately:

• Custom pages are a top-level collection with the course in the query string. A custom page is a static_tab block with its own usage key: its id in the list, the item of the reorder body, and /api/authoring/v1/xblocks/{usage_key}/ all address it by that key. ADR 0038 rule 8 puts such a resource at the top level with its parent in the query (the ADR's own units/?course_key= example). course_key is required.
• The order of a course's custom pages is a one-per-course noun, courses/{course_key}/custom_page_order/, replaced with PUT. v0's reorder verb becomes the noun (rule 10).
• Tabs are addressed by their course-scoped tab_id (progress, dates, wiki), so they stay under the course: courses/{course_key}/tabs/{tab_id}/, with PATCH {"is_hidden": …} returning the tab. Only the member is routed: listing every tab is not something v0 offered.

RISK, stated in the schema: a custom page is also one of the course's tabs (tab_id static_tab_<url_slug>), and the list shows that tab_id. PATCH …/tabs/static_tab_<url_slug>/ still answers 400 on is_hidden, as v0 does, because custom pages cannot be hidden. The PATCH description says so.

Why a new version and not a fix in place. Each of these changes the contract for v0's callers (the Pages & Resources custom pages screen calls the list and the reorder), so they ride v1 (ADR 0037):

• the list becomes paginated (a bare array becomes the seven-key envelope);
• the list moves to a new address, the reorder becomes PUT with a new body, and the tab change becomes PATCH on the member returning the tab;
• errors use the standard envelope, with fixed messages instead of text that echoed the request;
• Bearer tokens are refused;
• addresses gain a trailing slash and a checked course key.

Changes

Commit	Endpoint(s)	Legacy behaviour kept	New behaviour
feat: add a shared paginator that documents all seven envelope keys	—	DefaultPagination paging unchanged (page, page_size, 10 by default, at most 100)	New unversioned cms/djangoapps/contentstore/rest_api/pagination.py: DocumentedDefaultPagination, which publishes all seven envelope keys, each with an example. For this PR and the later Course Management lists
feat: add the pages and resources management permission class	—	CanViewPagesAndResources unchanged	CanManagePagesAndResources: the same user_has_course_permission(courses.manage_pages_and_resources, WRITE) call v0's reorder and settings views make inline
feat: serve course custom pages and tabs from authoring v1	the three v1 operations above (new)	v0 routes, views and URL names unchanged	Views, service, serializers, routes and tests. The service reuses the legacy helpers in views/tabs.py (get_course_tabs, reorder_tabs_handler, edit_tab_handler), which are not edited
docs: mark the v0 tabs endpoints deprecated in favour of authoring v1	the three v0 operations	Routes, views and responses unchanged	deprecated: true in the schema (three exact SUPERSEDED_PATHS entries); the docstring notes it added are reverted below
docs: remove the deprecation notes from the v0 tabs docstrings	the three v0 operations	v0 file back to its base content	A view docstring is the published description of the v0 operation, so the notes changed the legacy schema text and the OPTIONS body; SUPERSEDED_PATHS and the #39128 entry carry the deprecation
fix: refuse a null page item and a tab change that names no member	reorder, tab change	—	A null item in the order is refused before the items are read, with the same fixed message as any unusable item, and the schema publishes the item as string; a tab change naming no accepted member ({}, a misspelt is_hidden) is 400 with a fixed message under non_field_errors, as v0 was 400; the course_key query parameter says the value must be percent-encoded
docs: describe what an inactive session and a superuser are allowed	—	—	The authentication comment says what an inactive session gets instead of where the classes came from; the superuser test is renamed and gives the real reason a superuser is allowed (saving one sets is_staff)

ADRs applied

• 0025 serializers — separate output (CourseTab.v1, CustomPage.v1), request (CustomPageOrder.v1, CourseTabUpdate.v1) and query (CustomPageListQuery.v1) serializers, help_text on every field, explicit .v1 component names
• 0026 permissions — IsAuthenticated, the course key, IsExistingCourse, then the view or manage permission v0 checked inline; the list refuses any action it was not written for; deny matrix with policy permissions off and on
• 0027 schema / docs — @extend_schema on all three with summary, description (every 400 message named), parameters, examples and every 4xx as ErrorResponse; all three tagged openedx-platform-sdk
• 0028 viewsets — applied except router registration: three ViewSets over a service module, mounted with path(...) like every route in authoring_urls.py, because a router's regex routes cannot use the shared path converters
• 0029 errors — partial: the envelope on every response these views produce, with fixed messages; malformed JSON, 405, 406 and 415 are typed internal and a malformed course key on the nested routes gets the CMS HTML 404 (library and routing gaps, pinned by tests); detail still carries the library's ErrorDetail(...) text for validation errors while errors is clean
• 0030 GET idempotence — met for this code (no write, signal or event 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 v0
• 0031 merged endpoints — n/a: not merged, because the list and order act on custom pages and the visibility change on built-in tabs, which are different resources; the reorder verb became a noun under ADR 0038 instead
• 0032 pagination — the list returns the seven-key envelope (page, page_size 10 by default, at most 100) through the new shared DocumentedDefaultPagination, and the schema publishes all seven keys
• 0033 filtering — n/a: no filter or sort parameter; the order is the course's tab order, which is what learners see, and adding filters would be a new capability
• 0034 authentication — (JwtAuthentication, SessionAuthenticationAllowInactiveUser) declared with its reason, as ADR 0034 requires for an endpoint that used SessionAuthenticationAllowInactiveUser; Bearer dropped
• 0035 MFE config — n/a: per-course authoring data, not site or front-end configuration
• 0036 nested JSON — n/a: a flat list of thin objects (nine scalar members and a small settings map each) and a single tab
• 0037 versioning — partial: new modules in the current version, v0 not edited, deprecated: true in the schema through SUPERSEDED_PATHS; the DEPR entry on #39128 is posted; the removal follows [DEPR]: Contentstore and enrollment API versions superseded by FC-0118 #39128's window rather than a named release
• 0038 URL structure — custom_pages/?course_key= (rule 8), courses/{course_key}/custom_page_order/ (rule 10), courses/{course_key}/tabs/{tab_id}/; shared converter, trailing slash, version-free URL names; v0 names kept
• OEP-66 queryset scoping — n/a as a mechanism: the list reads one course's tab list from the modulestore, with no get_queryset(); the layering is shown in the matrix
• OEP-69 conventions — the decisions above as recorded, with the 0028, 0029, 0030 and 0037 departures stated; no governance identifiers in code or schema text

Compliance matrix

Decision	Status	How it is met, or the concrete reason it is excluded	Evidence (test / gate)
0025	met	CourseTabSerializer (CourseTab.v1: type, title (null for custom pages), is_hideable, is_hidden, is_movable, course_staff_only, name, tab_id, settings) and CustomPageSerializer (CustomPage.v1, adds the usage key id) give the same item v0's list returns. Request serializers for the order and the tab change; a query serializer for course_key. Explicit ref_names, because CourseTab already collides platform-wide	CustomPagesSchemaTest (test_the_tab_and_page_components, test_every_member_is_described, test_the_reorder_takes_json_naming_the_pages_and_answers_without_a_body, test_the_tab_change_takes_an_optional_is_hidden_and_returns_the_tab); CustomPagesListTest.test_the_body_matches_the_published_schema; hygiene H9
0026	met	Every v0 check has a v1 home (Authorization below). The list reads course_key from the query after the login check and before the course checks, so the order is 401, 400 (missing or invalid key), 404, 403. IsExistingCourse is unchanged: a permission step sets the view's course_key argument it reads. The list refuses any action other than list and OPTIONS with a server error. The order and tab viewsets check the manage permission for every action	CustomPagesAccessLegacyPermissionsTest, CustomPagesAccessAuthzTest (each access case asserts v0's answer too); CustomPagesPermissionWiringTest (test_the_listing_refuses_any_other_action, test_a_routed_action_the_listing_does_not_check_is_never_served); CustomPagesCourseKeyQueryTest (test_the_caller_is_authenticated_before_the_course_key_is_read, test_the_course_key_is_read_before_the_course_is_looked_up_or_the_caller_checked)
0027	met	Operation IDs v1_custom_pages_list, v1_courses_custom_page_order_update, v1_courses_tabs_partial_update. course_key is a required query parameter. The PUT description names all four 400 messages; the PATCH description says custom pages cannot be hidden there. All three are tagged openedx-platform-sdk; the deprecated v0 operations lose the tag through untag_deprecated_operations	CustomPagesSchemaTest (test_the_three_operations_are_published_for_the_sdk, test_the_list_parameters, test_the_reorder_documents_each_refusal_message, test_the_tab_change_says_custom_pages_cannot_be_hidden_there, test_the_examples_are_valid_bodies, test_the_v0_operations_are_deprecated_and_left_out_of_the_sdk)
0028	applied except router registration	CourseCustomPagesViewSet, CourseCustomPageOrderViewSet, CourseTabsViewSet (each StandardizedErrorMixin first, then viewsets.ViewSet) over v1/custom_pages_service.py. They are plain ViewSets because the data is the course's tab list in the modulestore. Deviation: mounted with path(), not a router	CustomPagesRoutingTest.test_the_addresses; CustomPagesListingCost{LegacyPermissions,Authz}Test
0029	partial	StandardizedErrorMixin first. 401 authn, 403 authz, 404 not-found (unknown, version-only or library course; a course the modulestore does not return; a tab_id the course does not have; a page out of range), 400 validation with errors keyed by member. Every refusal uses a fixed message that never echoes the request: course_key; the four reorder messages (not a usage key, not a custom page of this course, listed twice, could not be saved); is_hidden on a tab that cannot be hidden. When the reorder helper fails, its own text is logged with the course key and not returned. Gaps pinned by tests that flip when fixed: malformed JSON (400), 405, 406 and 415 are typed internal (edx-drf-extensions 10.9.0 does not catalogue them); a malformed key on the nested routes gets the CMS HTML 404 at routing; detail renders the validation detail with the library's ErrorDetail(...) text, while errors carries the plain messages	CustomPageOrderTest (test_an_item_that_is_not_a_string_holding_a_usage_key_is_refused_with_the_same_message, test_a_failure_saving_the_order_is_reported_without_its_text); CourseTabUpdateTest (test_a_tab_that_cannot_be_hidden_is_refused, test_a_tab_the_course_does_not_have_is_404); CustomPagesCourseKeyQueryTest.test_a_value_that_is_not_a_course_key_is_refused_without_echoing_it; CustomPagesRoutingTest (test_a_malformed_json_body_is_a_400_typed_internal, test_an_unsupported_media_type_is_a_415_typed_internal, test_other_methods_are_not_allowed, test_unsupported_accept_is_refused_with_406, test_an_unparsable_or_slash_form_key_is_an_html_404)
0030	met for this code; one inherited write	GET and HEAD read the course's tab list only. With policy permissions off and on, and with the pages-and-resources page flag on and off (it changes which tabs Studio walks), no listing writes to SQL or Mongo, stores through the modulestore, or sends a Django signal or Open edX event, including callbacks run on commit. The exception is the first read on a database without openedx-authz's PolicyCacheControl row, which inserts it (one INSERT, its pre_save/post_save). That write belongs to the permission library, happens on v0 too, and is allow-listed by name. The recorder's own self-tests live with the shared helpers in #39303	CustomPagesListingSideEffects{LegacyPermissions,Authz}Test (test_listings_have_no_side_effects, test_the_v0_listing_makes_the_same_first_lookup_write)
0031	excluded	Different resources (custom pages, built-in tabs); P18: a different resource is a reason not to merge	—
0032	met	IterablePaginationMixin with DocumentedDefaultPagination. Why a local subclass: edx-drf-extensions 10.9.0's DefaultPagination returns seven keys but publishes a response schema with four, so generated clients would drop num_pages, current_page and start. The subclass only adds get_paginated_response_schema, with an example per key so the generator can wrap a list example. It lives in an unversioned module so the later Course Management lists reuse it. The library fix is item L3 (to be filed); v2 textbooks' CourseTextbookPagination is a second copy, in a frozen file	CustomPagesListTest (test_the_envelope_has_the_seven_keys, test_page_size_splits_the_pages, test_the_default_page_size_is_ten, test_the_page_size_is_at_most_one_hundred, test_a_page_out_of_range_is_404); SharedPageEnvelopeTest; CustomPagesSchemaTest.test_the_list_publishes_the_seven_envelope_keys; hygiene H3 WARN (explained below)
0033	excluded	No filter or sort; fixed, documented order (the course's tab order). Unknown query parameters are ignored	CustomPagesListTest (test_only_the_custom_pages_are_listed_in_course_order, test_other_query_parameters_are_ignored)
0034	met with declared deviation	(JwtAuthentication, SessionAuthenticationAllowInactiveUser), commented at the declaration: an inactive account's browser session stays authenticated, so the course permission decides: staff status admits it, and its roles count only on courses where policy-based permissions are on. Bearer is dropped. Same as #39303	CustomPagesAuthenticationTest (test_a_jwt_caller_may_list_reorder_and_change_tabs, test_a_session_caller_may_list_reorder_and_change_tabs, test_an_inactive_session_is_authenticated, test_a_bearer_token_is_refused); hygiene H4
0035	excluded	Not configuration; per-course, per-user	—
0036	excluded	Flat list of thin objects; a single tab	—
0037	partial	New modules in v1/. v0 not edited: the file is identical to the base. deprecated: true through three exact SUPERSEDED_PATHS entries; no runtime header (frozen routes). DEPR: entry on #39128; the removal follows #39128's window	versions gate; CmsMarkSupersededPathsTest.test_the_tab_operations_are_marked_and_their_successors_are_not; CustomPagesSchemaTest (test_the_v0_operations_are_deprecated_and_left_out_of_the_sdk, test_only_superseded_or_migrated_addresses_are_deprecated)
0038	met	Rule 8 for custom pages (own usage key → top level, course in the query); rule 10 for the order; tab_id as the tab's natural key; shared course_key converter on the nested routes; trailing slash; version-free URL names	CustomPagesRoutingTest (test_the_addresses, test_the_v0_addresses_are_unchanged, test_the_url_names_are_unique_in_the_namespace, test_the_course_is_no_longer_part_of_the_list_address, test_the_list_address_without_its_trailing_slash_redirects_to_it, test_v0_still_takes_a_slash_separated_key_that_v1_does_not); CustomPagesCourseKeyQueryTest; url_snapshot rules check on a hand-built snapshot (the urls gate itself was skipped)
OEP-66	mechanism excluded, layering met	(1) endpoint access: the permission classes; (2) record visibility: the course's own tab list through get_course_tabs, keeping custom pages only, as on v0; (3) user selection: none beyond page/page_size, which cannot widen what is listed	access tests above; CustomPagesCourseKeyQueryTest.test_each_course_lists_its_own_pages
OEP-69	met	The decisions above, with the departures stated in their rows. No ADR/OEP/PR identifiers or narration in code or schema text	hygiene gate PASS (0 FAIL)

Backward compatibility

• v0 is unchanged. v0/views/tabs.py is not in the diff. Its routes, views and URL names are untouched, and v0's own tests are not edited.

• Parity. v1 is compared with v0 through the Django test client, with policy permissions off and on:

  • the list returns the same custom pages with identical members, on both sides of the pages-and-resources page flag;
  • a full reorder, and a reorder naming all pages but one, store the same tabs;
  • a visibility change stores the same tab.

  The only declared body differences, verbatim from the test module:

  INTENTIONAL_DIFFERENCES = [
      ("type", "errors use the standardized envelope"),
      ("title", "errors use the standardized envelope"),
      ("status", "errors use the standardized envelope"),
      ("detail", "errors use the standardized envelope"),
      ("errors", "a refused change names the refused member with a fixed message, where v0 returns the "
                 "helper's own text under developer_message"),
      ("developer_message", "the v0 error body carries developer_message; the envelope does not"),
      ("error_code", "the v0 not-found body carries error_code; the envelope does not"),
  ]

  The comparison fails both on an undeclared difference and on a declared difference that never occurs (_ParityMixin.test_every_declared_difference_occurs).

• Status and request differences from v0. Each is listed in the test module and observed against v0's own answer:

  RESPONSE_DIFFERENCES = [
      ("listing", "a bare array of every custom page", "a page of them in the standard envelope",
       "test_the_list_is_paginated"),
      ("change of a tab's visibility", "204 without a body", "200 with the tab",
       "test_a_visibility_change_returns_the_tab"),
      ("change of a tab the course does not have", "400", "404", "test_an_unknown_tab"),
      ("reorder naming a custom page that does not exist", "500", "400", "test_a_reorder_naming_no_page"),
      ("reorder naming a page twice", "204, the page stored twice", "400", "test_a_reorder_naming_a_page_twice"),
      ("any request for a course the modulestore returns nothing for", "500", "404",
       "test_a_course_the_modulestore_returns_nothing_for"),
      ("reorder leaving out two or more pages", "the pages left out in no particular order",
       "the pages left out in their current order", "test_pages_left_out_of_a_reorder"),
      ("reorder naming a page of another course with the same url_slug", "204, this course's page moved", "400",
       "test_a_page_of_another_course_with_the_same_url_slug"),
      ("OPTIONS by a signed-in caller without access, or for an unknown course", "200", "403 or 404",
       "test_options"),
      ("any request with a Bearer token", "2xx", "401", "test_a_bearer_token"),
      ("listing for a slash-separated course key", "404 JSON", "400", "test_a_slash_separated_course_key"),
  ]

  As a table, with the request-shape changes that carry no status difference:

  Request	v0	v1	Test
  list	GET v0/tabs/{course_id}, bare array	GET v1/custom_pages/?course_key=, 7-key envelope, 10 per page by default	CustomPagesResponseDifferencesTest.test_the_list_is_paginated
  list for a slash-form course key	404 JSON	400 errors.course_key	…test_a_slash_separated_course_key
  reorder	POST …/reorder with [{tab_id}|{tab_locator}]	PUT …/custom_page_order/ with {"custom_pages": [<usage key>, …]}; same stored tabs	_ParityMixin.test_reorders_store_the_same_tabs
  reorder leaving out two or more pages	left-out pages in no particular order	left-out pages in their current order	…test_pages_left_out_of_a_reorder
  reorder naming another course's page with the same url_slug	204, this course's page moved	400	…test_a_page_of_another_course_with_the_same_url_slug
  reorder naming a page that does not exist	500	400	…test_a_reorder_naming_no_page
  reorder naming a page twice	204, page stored twice	400	…test_a_reorder_naming_a_page_twice
  show or hide a tab	POST …/settings?tab_id= → 204, no body	PATCH …/tabs/{tab_id}/ → 200 with the tab	…test_a_visibility_change_returns_the_tab
  tab the course does not have	400, echoing the tab id	404, fixed message	…test_an_unknown_tab
  tab change without is_hidden ({}, or a misspelled member)	400, DRF's "This field is required." under is_hidden	400, fixed message under non_field_errors	…test_a_change_naming_no_known_member_is_refused_by_both; CourseTabUpdateTest.test_a_body_without_is_hidden_is_refused_and_changes_nothing
  tab that cannot be hidden	400 with the helper's text	400, fixed message under is_hidden	_ParityMixin.test_a_refused_visibility_change_names_is_hidden_with_a_fixed_message
  course the modulestore returns nothing for	500	404	…test_a_course_the_modulestore_returns_nothing_for
  OPTIONS by an outsider, or for an unknown course	200	403 / 404	…test_options
  Bearer token	2xx	401	…test_a_bearer_token
  address without the trailing slash	served	301 to the slashed address, query kept	CustomPagesRoutingTest.test_the_list_address_without_its_trailing_slash_redirects_to_it

  The tab_locator form of v0's settings endpoint has no successor. It can only name a custom page, which can never be hidden.

• Query counts. A listing runs no more SQL queries or Mongo reads than v0's, measured in the same test on both sides of the pages-and-resources flag. Its SQL count does not grow with the number of pages. No literal baseline was measured, because no platform environment was available.

• Schema. Three new operations, and deprecated: true on the three v0 operations. docs/cms-openapi.yaml is not edited; the generate_openapi_schemas workflow regenerates it.

In-place edits

File	Category	Evidence
cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py	strictly opt-in addition: one import, three routes	no line removed; CustomPagesRoutingTest
cms/djangoapps/contentstore/views/permissions.py (shared, unversioned)	one class added; the existing openedx_authz.constants.permissions import gains one name; existing classes unchanged	CustomPagesPermissionWiringTest and the access tests
cms/djangoapps/contentstore/rest_api/pagination.py (new, unversioned)	new shared module	SharedPageEnvelopeTest, CustomPagesSchemaTest.test_the_list_publishes_the_seven_envelope_keys
cms/lib/spectacular.py, cms/lib/tests/test_spectacular.py	three exact SUPERSEDED_PATHS entries; the exact-set test updated and a test for the tab paths added	CmsMarkSupersededPathsTest

New files inside the pre-existing v1/: custom_pages_service.py, serializers/custom_pages.py, views/custom_pages.py, views/tests/test_custom_pages.py. They import nothing from rest_api/v0/.

Error-format decision

Versioned. v0 keeps its developer_message/error_code bodies, its 500s and the helpers' text unchanged. v1 uses the envelope with fixed messages. The custom pages screen in frontend-app-authoring calls the v0 list and reorder (src/custom-pages/data/api.ts); the list's pagination already forces a new version, and the error format rides with it.

Deprecations

The three v0 operations are superseded by the three v1 operations in the Summary. They are deprecated: true in the CMS schema; the v0 views are not edited and send no runtime header. Tracked on the FC-0118 umbrella DEPR ticket, #39128; this resource's entry is posted there. Window per #39128: removed one named release after the release this ships in.

Migration notes:

• List: call GET /api/authoring/v1/custom_pages/?course_key={course_key}. It is paginated: read results, and follow next or pass page/page_size (at most 100) to get every page. Items are unchanged, including id.
• Reorder: PUT /api/authoring/v1/courses/{course_key}/custom_page_order/ with {"custom_pages": [<usage key>, …]}, the ids from the list (v0's tab_locator values). Pages left out follow the listed ones in their current order. Answers 204.
• Show or hide a tab: PATCH /api/authoring/v1/courses/{course_key}/tabs/{tab_id}/ with {"is_hidden": true|false}. Answers 200 with the tab. A body without is_hidden is refused (400, fixed message under non_field_errors).
• Refusals use fixed messages under the member they concern (course_key, custom_pages, is_hidden, or non_field_errors for a tab change naming no member).
• The list's course_key is a query parameter now, so it must be percent-encoded: an unencoded + reads as a space and is refused (send course-v1%3AedX%2BDemoX%2B2026).
• Errors use the standard envelope.
• Bearer tokens are refused; use JWT or a session.
• Every address ends with a slash.

Authorization

Legacy check	Where it lives in v1	Deny-path tests
@view_auth_classes(is_authenticated=True) on all three views	IsAuthenticated, before the course key is read	test_anonymous_caller_is_refused_with_401 (both permission modes), incl. on an unknown course; CustomPagesCourseKeyQueryTest.test_the_caller_is_authenticated_before_the_course_key_is_read
@verify_course_exists() on all three methods	IsExistingCourse (also 404 for version-only and library keys); for the list, after the query's course_key is validated	unknown course, version-only key and library key → 404, before any role check (test_unknown_course_is_404_before_permission_is_checked, test_a_version_only_course_key_is_404, test_a_library_is_not_a_course, CustomPagesCourseKeyQueryTest.test_a_version_only_or_library_key_is_an_unknown_course)
user_has_course_permission(courses.view_pages_and_resources, READ) in the list	CanViewPagesAndResources (existing), same call	no role; staff/instructor of another course; limited staff; policy roles limited staff, data researcher, beta tester; an admin role on another course; legacy staff without a policy role when policy permissions are on
user_has_course_permission(courses.manage_pages_and_resources, WRITE) in reorder and settings	CanManagePagesAndResources (new), same call	as above, plus the view-only policy role (auditor) → 403 on reorder and tab change (test_a_role_that_may_only_view_may_list_but_not_reorder_or_change_tabs)

Order: 401, then 400 for a missing or invalid course_key (list only), then 404 for a missing course, then 403. Allowed: course staff and instructor, org staff and instructor, global staff, and superusers, as on v0: saving a superuser also sets is_staff, so every superuser is global staff (test_a_superuser_is_allowed). With policy permissions on, the roles that grant viewing (list) or managing (reorder, tab change) pages and resources are allowed: auditor views; editor, staff and admin manage.

Gate report

Run on the host against 9b4d60ea0d (the head of #39303, which this branch stacks on). No platform environment was available, so four gates were skipped locally. The test module runs in CI.

Gate	Result
versions	PASS: 1 ALLOWED (v1/authoring_urls.py), 4 ADDED, nothing protected touched (23 shared legacy modules protected, including views/tabs.py, whose helpers v1 reuses)
hygiene	PASS (0 FAIL, 1 WARN). The WARN is H3 on DocumentedDefaultPagination, a local subclass of a library paginator. It is kept on purpose: it adds the seven-key response schema the library lacks (see 0032) and says so in its docstring
ruff	clean; no line over 120 characters
supplementary, not a gate: URL rules (url_snapshot.py check) on a hand-built snapshot of the new routes	PASS (0 FAIL, 0 WARN); the real urls gate above is SKIPPED
schema	SKIPPED (no platform environment)
urls	SKIPPED (no platform environment)
old-tests	SKIPPED (no platform environment)
tests	SKIPPED locally (no platform environment); CI runs them. CI green on the previous head apart from an unrelated Firefox JS flake (VideoVolumeControl ARIA test); the two pylint C0116 hits are fixed in 8d66706

Follow-ups

• SDK: all three operations carry openedx-platform-sdk; the next openedx-platform-sdk regeneration gains them.
• frontend-app-authoring: the custom pages screen (src/custom-pages/data/api.ts) can move to the v1 list (request page_size=100 or follow next) and the PUT order. No MFE caller uses the v0 settings endpoint today.
• edx-drf-extensions:
  • L3: DefaultPagination.get_paginated_response_schema with all seven keys, after which DocumentedDefaultPagination can be deleted. Issue to be filed.
  • Catalogue ParseError, MethodNotAllowed, NotAcceptable and UnsupportedMediaType.
  • Render a validation detail without the ErrorDetail(...) text.
• v2 textbooks: CourseTextbookPagination (frozen in v2/views/textbooks.py) duplicates the shared paginator's schema; point the next version of that resource at rest_api/pagination.py.
• 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.
• Authentication across /api/authoring/: v1 here, feat: serve course advanced settings from authoring v1 #39303 and the feat: apply FC-0118 ADRs to course content APIs #39157 v2 views keep SessionAuthenticationAllowInactiveUser; feat: serve the course outline from authoring v2 #39229 and feat: serve course containers from authoring v2 #39274 use the default. One policy for new versions of such endpoints should be agreed.
• Sibling PR B (course optimizer) edits the same shared files: views/permissions.py, v1/authoring_urls.py, cms/lib/spectacular.py and its test. The conflicts are additive, resolved by rebasing in merge order. When both land, the merged openedx_authz.constants.permissions import must be wrapped to stay within 120 characters.

[openedx-webhooks]

Thanks for the pull request, @taimoor-ahmed-1!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform-oncall.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[Faraz32123]

Reviewed locally (this PR's 5 commits): 429 passed, schema diff clean (0 breaking). Auth, course existence, list/reorder/settings permissions, rows and write paths match v0. Looks good overall, a few points:

• Deprecation notes in the v0 docstrings (inline).
• Minor: error detail is the Python repr of the errors dict (declared follow-up for edx-drf-extensions).
• pylint cms is red on two C0116 in v1/views/tests/test_custom_pages.py (514, 1195).
• PR body still lists tests/schema as SKIPPED.
• Inherited, FYI only: courses that already have a duplicated custom page (v0 reorder can store one) list it twice on v1 too.

All findings were compared with the previous version's behaviour; anything inherited from it is marked as such.

[Faraz32123]

Can we drop this deprecation note? We agreed on #39100 not to add DEPR notes in docstrings. This docstring is the published description of the v0 operation, so it changes the legacy schema text and puts an issue URL into it (which also makes the OEP-69 tick untrue). SUPERSEDED_PATHS plus the #39128 entry already carry the deprecation. Same for the other notes in this file.

[taimoor-ahmed-1]

Dropped: v0/views/tabs.py is back to its base content (47667a7). SUPERSEDED_PATHS and the #39128 entry carry the deprecation.

[Faraz32123]

allow_null=True publishes the item as string | null, but a null item is always refused with 400. Generated SDKs will accept a value the server rejects. Could the list validator refuse null instead?

[taimoor-ahmed-1]

Done (8d8e215 on #39304 is unrelated; here it's 8d66706): allow_null is gone from the item field, and the list refuses a null item before the items are read, with the same fixed message as any other unusable item. The schema now publishes the item as string, and a test pins the whole item schema.

[Faraz32123]

Declared, but worth a second look: a misspelled body like {"is_hiden": true} returns 200 and changes nothing, where v0 gave 400. Maybe refuse a body with no known member?

[taimoor-ahmed-1]

Changed my mind on this one: a body naming no member a tab accepts ({}, {"is_hiden": true}) is now 400 with a fixed message under non_field_errors, as v0 was 400 (8d66706). That removes the "change without is_hidden" row from the declared differences; the case is a parity error pair now. One knock-on: the body is read before the tab is looked up, so an empty body to an unknown tab is 400, not 404, which v0 also did.

[Faraz32123]

Since the course key moved from path to query, an unencoded + decodes to spaces and gives 400. Could the parameter description / migration notes say the value must be percent-encoded?

[taimoor-ahmed-1]

The parameter description now says to percent-encode the value, with course-v1%3AedX%2BDemoX%2B2026 as the example and the reason (an unencoded + reads as a space), and a test sends the unencoded form and checks the 400 (8d66706). The migration notes in the description say the same.