Migrate Studio API callers to standardized v3/v4 endpoints (FC-0118)

[taimoor-ahmed-1]

Summary

Five Studio REST APIs on edx-platform have been standardized under FC-0118 (ADRs 0025–0037) and released as new versions. frontend-app-authoring is the sole MFE consumer of all five and needs to migrate its callers.

The old versions remain live (no immediate breakage), but the new versions offer a standardized error envelope, OpenAPI 3.x schemas, ADR 0036 ?view=minimal / field-selection presets, and consistent auth. New Studio features should target the new versions; existing call sites should be migrated opportunistically.

Update — incorporating @bradenmacdonald's feedback:

• Items [BD-03] [BB-2542] ]Add discussions configuration UI wireframe in MFE #2 (Course Home) and adds transifex config and test string #3 (Home Courses) are on hold pending Switch from Redux to React Query + Context #2540, which proposes breaking up the "Studio Home" kitchen-sink state (course list, library list, permissions, feature flags, branding) into smaller, purpose-specific queries. Versioning those endpoints as-is would entrench a shape we intend to remove, so we'll revisit once Switch from Redux to React Query + Context #2540's direction is settled.
• A standardized error-handling wrapper for React Query (parsing the ADR 0029 envelope) should land before the per-API migrations — see Prerequisites.

APIs to migrate

#	Old URL	New URL	Status
1	Legacy /xblock/{usage_key}/ (non-REST)	/api/contentstore/v1/xblock/{usage_key}/	Ready
2	/api/contentstore/v1/home/	/api/contentstore/v3/home/	⏸ On hold (#2540)
3	/api/contentstore/v2/home/courses/	/api/contentstore/v4/home/courses/	⏸ On hold (#2540)
4	/api/contentstore/v1/course_details/{course_id}	/api/contentstore/v3/course_details/{course_id}	Ready
5	/api/contentstore/v1/course_grading/{course_id} (GET+POST)	/api/contentstore/v3/authoring_grading/{course_id} (single PATCH)	Ready

Prerequisite — standardized error wrapper

Before migrating any call site, add a thin React Query wrapper around getAuthenticatedHttpClient() that parses the ADR 0029 standardized error envelope:

{
  "error": {
    "type": "validation_error",
    "detail": "…human-readable message…",
    "errors": [
      { "code": "required", "field": "display_name", "detail": "…" }
    ]
  }
}

The wrapper should:

1. Read response.data.error.detail (falling back to response.data.detail so v1 callers keep working during the migration).
2. Map response.data.error.errors[] onto a fieldErrors object keyed by field name, for form UIs (Schedule & Details, Grading Settings).
3. Return a normalized { detail, fieldErrors, code } shape so consumers never read error.response.data directly.

Landing this first gives one place to add tracing/logging and keeps each per-API PR small. (Envelope shape from ADR 0029; implemented via StandardizedErrorMixin at openedx/core/lib/api/mixins.py.)

Call sites (grepped 2026-07-03)

1. Xblock — legacy /xblock/ → /api/contentstore/v1/xblock/

Every current call goes through the legacy Studio route, not the REST endpoint. Consolidating them behind the new v1 REST viewset also gives us proper OpenAPI schemas for SDK generation.

• Course Unit — src/course-unit/data/api.ts:22,75,103,127,137
• Course Outline — src/course-outline/data/api.ts:42,162,177,194,214,267,307,331,347,360,377,394,409,427,443
• Custom Pages — src/custom-pages/data/api.js:29,41,55
• Course Updates — src/course-updates/data/api.js:69,81
• XBlock Editors — src/editors/data/services/cms/urls.ts:44-58,124
• Content Tags Drawer — src/content-tags-drawer/data/api.js:32,85

2. Course Home v1 → v3 — ⏸ on hold (#2540)

• src/studio-home/data/api.ts:6,14,54 (Studio Home landing + libraries tab)

Deferred: #2540 intends to split this endpoint's kitchen-sink payload into smaller queries; bumping the version first would be wasted work.

3. Home Courses v2 → v4 — ⏸ on hold (#2540)

• src/studio-home/data/api.ts:20 (v1 fallback — drop), :31 (v2 caller — bump to v4)

Deferred for the same reason as #2.

4. Course Detail v1 → v3

• src/schedule-and-details/data/api.js:6,17 (getCourseDetails)
• src/schedule-and-details/data/api.js:30 (updateCourseDetails)

5. Author Grading v1 (GET+POST) → v3 PATCH

The v3 endpoint collapses the two-endpoint pattern into a single partial_update.

• src/grading-settings/data/api.js:7,17,29 — helpers getGradingSettingsApiUrl, getGradingSettings, sendGradingSettings
• src/grading-settings/data/apiHooks.ts:7,21 — React Query hooks

Suggested approach

• Land the standardized-error React Query wrapper first (see Prerequisite).
• Then one PR per Ready API — Initialize repo for new MFE, port 2001 #1 (Xblock), mroytman/MST 286 add proctored exam settings component #4 (Course Detail), fix(i18n): update translations #5 (Author Grading) — so each ships independently and rolls back cleanly.
• Defer [BD-03] [BB-2542] ]Add discussions configuration UI wireframe in MFE #2 (Course Home) and adds transifex config and test string #3 (Home Courses) until Switch from Redux to React Query + Context #2540 is resolved.
• ADR 0036 ?view=minimal is opt-in and defaults to the full payload — no changes needed to consumer code unless you want the trimmed payload.

References

ADRs (on openedx/edx-platform, branch feat/axim-api_improvements pending merge to master):

• 0025 — Standardize serializer usage
• 0026 — Standardize permission classes
• 0027 — Standardize API documentation & schema coverage
• 0028 — Migrate to DRF ViewSets
• 0029 — Standardize error responses
• 0031 — Merge similar endpoints
• 0034 — Unify auth (JWT + Session, drop BearerAuth/OAuth2)
• 0036 — Normalize deeply nested JSON APIs
• 0037 — API versioning strategy

PRs: #38684 (Home v4), #38694 (Home v3), #38708 (Course Details v3), #38723 (Xblock v1), #38724 (Enrollment v2), #38726 (Author Grading v3), #38773 (ADR 0036 pass), #38796 (ADR 0034 pass), #38834 (Xblock v1 OpenAPI schema).

Related: #2540 (break up Studio Home state).

[bradenmacdonald]

Is there a link to the ADR or the PR that made these changes? Because I've been wanting to get rid of the "studio home" API altogether, and I'm wondering why we're releasing a new version of it at all.

One thing I'd like to get rid of entirely is the weird "Studio Home" state which has become a kitchen sink of data (course list, library list, user permissions, feature flags, branding/theming). I think the idea was to improve loading times by loading all the data needed to render the studio home page from a single API, but it's just messy now. And today a few small parallel requests that are definitely needed are better than one big request that ends up loading unused data. So that should be broken up into smaller things (course list query, library list query, users permissions query, etc.) and more specific contexts.

• noted on Switch from Redux to React Query + Context #2540

[bradenmacdonald]

As part of this work, if the new endpoints have standardized error responses, we also need a nice wrapper function for calling these APIs from React Query, which can properly parse and report errors in a standardized way.

[taimoor-ahmed-1]

As part of this work, if the new endpoints have standardized error responses, we also need a nice wrapper function for calling these APIs from React Query, which can properly parse and report errors in a standardized way.

Thanks for the review, @bradenmacdonald — I've updated the issue accordingly:

• Corrected the ADR range to 0025–0037.
• Put Course Home and Home Courses on hold pending the Studio Home state refactor (Switch from Redux to React Query + Context #2540), and marked them as such in the APIs table and call-site sections.
• Added a standardized-error React Query wrapper as a prerequisite (parses the ADR 0029 error envelope), with the suggested approach now sequencing the wrapper first, then the three Ready APIs.
• Let me know if anything still looks off.

[bradenmacdonald]

Thanks @taimoor-ahmed-1 , sounds good!