[FC-0118] docs: ADR for documenting and consolidating internal MFE APIs - #38309
Conversation
There was a problem hiding this comment.
As a frontend developer, it would be great to have better-documented (and behaved) edx-platform REST APIs . But I have a couple of major concerns about this ADR as stated, at the moment.
Concern 1: It seems it's trying to decide two things at once: that a) existing endpoints should be better documented, and b) that there should be a new consolidated endpoint for configuration and context data. My first suggestion is to split this into two ADRs.
Concern 2: This is about the "b)" part of the ADR. I dislike multi-purpose endpoints, however well documented, however useful they might seem, for the simple fact that they go against RoA. Sure, edx-platform's REST API is only now being seriously designed, but that doesn't mean we should start implementing a new verb soup.
Finally, out of curiosity: is this part of #38137?
| Context | ||
| ------- | ||
|
|
||
| Multiple Open edX MFEs depend on undocumented internal LMS APIs. This causes two concrete problems: |
There was a problem hiding this comment.
It would be good to have a list of these uses. It doesn't need to be comprehensive (certainly not in this ADR), but we should have a draft in the wiki we can point to. It will make this ADR's case much more compelling.
There was a problem hiding this comment.
Agreed. I'll put together a draft wiki page (representative, not exhaustive) of the undocumented endpoints MFEs depend on today and link it from the revised ADR. Tracking this before the next revision.
|
|
||
| Multiple Open edX MFEs depend on undocumented internal LMS APIs. This causes two concrete problems: | ||
|
|
||
| 1. **Runtime breakages**: Backend refactors silently break MFE data fetches because there |
There was a problem hiding this comment.
Do we have an example (or two, or three) of when such a breakage happened?
There was a problem hiding this comment.
Here are few exmaples which i was able to find with the help of claude ofcourse
On concrete cases of release-to-release breakages, three recent ones:
- Teak — Discussion threads silently returning empty (Dec 2025). GET /api/discussion/v1/threads/ started returning 200 OK with {"results": []} for any topic lookup after edx-platform#36820 ("feat!: remove cs_comments_service support for forum's search APIs") moved a commentable_ids list conversion inside a search-only branch. The PR description said "no impact on end-users" — but the Discussion MFE was broken for everyone on a fresh Teak install. Fix had to be backported. Forum thread.
- Teak — POST /api/discussion/v1/threads/ 500ing on every call (Aug 2025). edx-platform's CommentClient called forum_api.get_user(...) without group_ids, while the openedx/forum 0.2.0 that shipped with Teak still had it as required positional. Every thread creation returned 500 until Teak.2 bumped the forum version. Forum thread.
- /api/mfe_context optional fields regression (Mar 2026). Backend returns optionalFields in the payload, Authn MFE silently doesn't render them after upgrade to Tutor 20 / Ulmo. Exactly the class of undocumented MFE-context endpoint this ADR is about. Forum thread.
Happy to add these into the ADR's Context section if useful.
There was a problem hiding this comment.
These are great examples and I think we can document them in the ADR, as a part of the historical record.
| Decision | ||
| -------- | ||
|
|
||
| We will document and consolidate all internal APIs used by MFEs into stable, |
There was a problem hiding this comment.
And here's my main concern with this ADR:
Why does it have to be about MFEs? Certainly it makes sense for edx-platform to have stable, documented REST APIs that are usable by any clients, not just our own MFEs. This is, of course, a massive undertaking, but it has already started via #38137. Is this a part of that?
There was a problem hiding this comment.
Agree, this was a framing mistake. The underlying problem, undocumented endpoints with no contract guarantees, isn't MFE-specific; MFEs are just the most visible current consumer. I'll rewrite the framing to be about the platform's REST surface generally (under #38137), with MFEs as one motivating example rather than the scope. Confirming for the thread above: yes, this is part of #38137.
|
|
||
| * All backend APIs consumed by MFEs MUST be documented with OpenAPI specifications, | ||
| including field descriptions, types, and example responses. | ||
| * Consolidate MFE configuration into a single, documented endpoint per MFE context |
There was a problem hiding this comment.
This seems like an independent decision. There already is an ADR for it.
There was a problem hiding this comment.
I missed the existing ADR 0001 for /api/mfe_config/v1/, which already covers the mfe=<name> parameter. I won't be re-deciding that here. If MFEs need something 0001 doesn't already cover, the right vehicle is an amendment/follow-up to 0001, not a duplicate decision in this ADR.
| * Consolidate MFE configuration into a single, documented endpoint per MFE context | ||
| (target pattern: ``/api/mfe_config/v1/``). | ||
| * The consolidated endpoint MUST accept ``mfe=<name>`` for app-specific overrides and | ||
| MAY accept ``course_id`` for course-contextual data (see `Authentication & Authorization`_ |
There was a problem hiding this comment.
And this is yet another decision. Is this ADR supposed to be about API documentation, or the creation of a new configuration endpoint?
(By the way, there already is a new configuration endpoint: /api/frontend_site_config/v1. I'm not sure we want to create yet another one, so soon.)
There was a problem hiding this comment.
Both which is the scoping problem you flagged up top, so I'll split. And thanks for pointing to /api/frontend_site_config/v1; Adding a third config endpoint isn't on the table. The right question is whether the existing two cover what MFEs need today, and that's an audit I'll do it
| * The consolidated endpoint MUST accept ``mfe=<name>`` for app-specific overrides and | ||
| MAY accept ``course_id`` for course-contextual data (see `Authentication & Authorization`_ | ||
| below for scope rules). | ||
| * Deprecate undocumented internal endpoints once a supported, documented replacement |
There was a problem hiding this comment.
A minor quibble with the naming choice: if you mean REST endpoints, they're external by definition, even if not documented properly.
And, again, I'd be curious to learn of cases where REST endpoints were broken from one release to the next.
|
|
||
| * **Public configuration** (``BASE_URL``, ``LMS_BASE_URL``, feature flags): No | ||
| authentication required. Highly cacheable. | ||
| * **User-contextual data** (user roles, course-specific permissions): Requires a valid |
There was a problem hiding this comment.
Again, I'm looking at a separate ADR, here. What you seem to be suggesting is a single new multi-purpose endpoint that would be useful exclusively for MFEs.
I'm sorry to say that I'm not in favor of this, as it goes against resource-oriented API design. The key concept is that each API resource can be reused for different purposes, and a monolithic endpoint would be the antithesis of this.
There was a problem hiding this comment.
Agreed and addressed in more detail in my top-level reply. The multi-purpose endpoint piece is coming out of the proposal entirely. User roles and course permissions belong as their own resources, usable by any client, not as fields on a config blob.
Faraz32123
changed the title
Thanks you for reviewing it, these are fair concerns and on reviewing them I think they point to a real scoping problem on my side. Let me address them in turn.Please share your thoghts on them On Concern 1 (two decisions in one ADR): You're right, and splitting is the right call. "Document the endpoints MFEs currently depend on" and "consolidate MFE configuration into one endpoint" are genuinely separate decisions, and bundling them makes both harder to evaluate. The documentation piece also overlaps with #38189 (drf-spectacular adoption), so I want to make sure I'm not re-deciding that here either.So for this ADR lets just focus on consolidate MFE configuration into one endpoint only since #38189 covers the docuementation thing On Concern 2 (multi-purpose endpoint + RoA): This is the more important point and I agree. What I described drifts toward an RPC-style "give an MFE everything it needs in one call" endpoint, which is the wrong direction when the platform is only now adopting proper resource-oriented design. User-role and course-permission data shouldn't be folded into a config endpoint — those belong as their own resources (e.g. On the existing endpoints I missed: I overlooked both ADR 0001 for On #38137: Yes, this is intended to live under that epic, same FC-0118 umbrella as #38189.
Does that direction sound right? Happy to correct now rather than rework after. |
|
Sounds good to me! Thanks, @Abdul-Muqadim-Arbisoft! |
|
@Abdul-Muqadim-Arbisoft it looks like this ADR has not been updated since your discussion with Adolfo. Is the plan to make those updates inline or close this and open new PRs or something else? |
|
Hi @feanil @arbrandes, quick question before I push the revised draft. After some rnd i landed on a clear finding: Before I push, want to check the right shape: Option A: keep this PR; push the revised ADR as a new file (0040, current working title "Canonical MFE Configuration Endpoint"). Marks ADR 0001 as Option B: close this PR; open a new PR that amends ADR 0001 directly. Either by replacing the body with the new decision plus a history note, or by appending an "Update 2026" section to 0001. Option C: push 0040 here, and follow up with a tiny PR adding a I think option A or C might be better because amending an accepted ADR is unusual in the ADR convention I'm most familiar with. But happy to follow whatever openedx actual practice is, your call. |
adf2e7b to
ad4b7ba
Compare
Define a plan to document all undocumented internal LMS APIs consumed by MFEs into stable, OpenAPI-described contracts. Introduces a consolidated config endpoint pattern with optional course/user context, authentication boundaries, and a rollout plan following OEP-21 DEPR process.
f2da5cb to
957bdb1
Compare
|
@Abdul-Muqadim-Arbisoft I agree with you, I think we should go with Option A, we'll land this ADR and this PR should update 0001 to reflect that it's superseded by 0040. @arbrandes let me know if you have any concerns with that. |
|
Option A is fine by me! 👍🏼 |
Record that /api/frontend_site_config/v1/ is the canonical endpoint for MFE/front-end runtime configuration (frontend-base SiteConfig, OEP-65) and that /api/mfe_config/v1 is legacy, on the DEPR path tracked in openedx#37255 and added, and that user-context data (roles, permissions) belongs on resource-oriented endpoints rather than on a configuration payload. Documentation/schema coverage is deferred to the API Documentation & Schema Coverage ADR (openedx#38189). Partially supersedes ADR 0001 (MFE Config API). Part of FC-0118 Open edX REST API standardization (openedx#38137). Refs openedx#38280 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
d92c03c to
fe8f3af
Compare
feanil
left a comment
feanil
left a comment
There was a problem hiding this comment.
Generally looks good, I don't know how much value it provides to say we didn't document this previously but we're documenting it now. We can just say, the API was added, this ADR provides rationale and context. But fine to merge as is or with that update.
Asked for links in one place but it looks like they are in the reference. So the inline links are nice to have but also not needed. I don't need to re-review before you merge.
|
|
||
| Multiple Open edX MFEs depend on undocumented internal LMS APIs. This causes two concrete problems: | ||
|
|
||
| 1. **Runtime breakages**: Backend refactors silently break MFE data fetches because there |
There was a problem hiding this comment.
These are great examples and I think we can document them in the ADR, as a part of the historical record.
| OEP-65. New consumers MUST target it. | ||
| * **Legacy endpoint on a deprecation path.** ``/api/mfe_config/v1`` | ||
| (``MFEConfigView``, ADR 0001) is legacy. Its deprecation follows OEP-21 and is | ||
| tracked in #37255 and #37210, targeting the Verawood (2026-04) named release. |
7ec0881
into
openedx:docs/ADRs-axim_api_improvements
* docs: ADR for documenting and consolidating internal MFE APIs Define a plan to document all undocumented internal LMS APIs consumed by MFEs into stable, OpenAPI-described contracts. Introduces a consolidated config endpoint pattern with optional course/user context, authentication boundaries, and a rollout plan following OEP-21 DEPR process. * docs: add ADR for canonical MFE configuration endpoint Record that /api/frontend_site_config/v1/ is the canonical endpoint for MFE/front-end runtime configuration (frontend-base SiteConfig, OEP-65) and that /api/mfe_config/v1 is legacy, on the DEPR path tracked in #37255 and added, and that user-context data (roles, permissions) belongs on resource-oriented endpoints rather than on a configuration payload. Documentation/schema coverage is deferred to the API Documentation & Schema Coverage ADR (#38189). Partially supersedes ADR 0001 (MFE Config API). Part of FC-0118 Open edX REST API standardization (#38137). Refs #38280
* docs: ADR for documenting and consolidating internal MFE APIs Define a plan to document all undocumented internal LMS APIs consumed by MFEs into stable, OpenAPI-described contracts. Introduces a consolidated config endpoint pattern with optional course/user context, authentication boundaries, and a rollout plan following OEP-21 DEPR process. * docs: add ADR for canonical MFE configuration endpoint Record that /api/frontend_site_config/v1/ is the canonical endpoint for MFE/front-end runtime configuration (frontend-base SiteConfig, OEP-65) and that /api/mfe_config/v1 is legacy, on the DEPR path tracked in #37255 and added, and that user-context data (roles, permissions) belongs on resource-oriented endpoints rather than on a configuration payload. Documentation/schema coverage is deferred to the API Documentation & Schema Coverage ADR (#38189). Partially supersedes ADR 0001 (MFE Config API). Part of FC-0118 Open edX REST API standardization (#38137). Refs #38280
* docs: add ADR for standardizing serializer usage (#38139) * docs: explicitly mention API versioning incase of backwards incompatible change (#38188) Co-authored-by: Muhammad Faraz Maqsood <faraz.maqsood@A006-01130.local> * docs: add ADR for standardizing permissions usage (#38187) Currently, authorization logic is implemented inconsistently across views, serializers, and custom access checks. This ADR will define a consistent approach using DRF permission classes, object-level permissions, and queryset scoping where appropriate. Co-authored-by: Taimoor Ahmed <taimoor.ahmed@A006-01711.local> * docs: minor change in ADR language * fix: add s back * docs: migrate restful & legacy django api endpoints to standard drf viewsets (#38191) * docs: Add ADR for ensuring GET requests are idempotent Add edx-platform/docs/decisions/0030-ensure-get-requests-are-idempotent.rst as an accepted ADR. Define policy that GET endpoints must be strictly read-only, with side effects moved to explicit write endpoints or async event pipelines. Include edx-platform relevance, anti-pattern vs preferred code examples, and rollout guidance for testing and migration. * docs: add ADR for standardizing API documentation and schema coverage - Propose adoption of drf-spectacular across Open edX services - Require @extend_schema decorators for all API endpoints - Document request/response schemas, status codes, and error conditions * docs: remove incorrect ADR number * docs: address api-doc-tools deprecation in ADR per review feedback - Add context explaining what api-doc-tools is and its relationship to drf-yasg - Document deprecation and archival of api-doc-tools as a consequence - Add migration guide mapping api-doc-tools decorators and URL helpers to their drf-spectacular equivalents - Add rejected alternative for updating api-doc-tools internals - Add rollout step for final archival cutover Closes review comment by @feanil * docs: expand ADR-0027 with api-doc-tools deprecation and drf-yasg incompatibility analysis Address review feedback on FC-0118 ADR 0027: - Add context paragraph explaining what api-doc-tools is (drf-yasg shim, decorators it provides, schema view, OpenAPI 2.0 output) - Document deprecation of api-doc-tools and drf-yasg as a consequence, including transition-window behavior - Add detailed 8-point incompatibility analysis explaining why drf-yasg cannot be replaced with drf-spectacular inside api-doc-tools (recorded in the ADR itself for future reference) - Add migration plan for existing api-doc-tools consumers with concrete decorator/import/setting mapping - Update Rollout Plan to track api-doc-tools removal - Add references to drf-spectacular migration guide, drf-yasg upstream status, and api-doc-tools repository * chore: fix edx-mantained to edX-platform * docs: add ADR for standardizing pagination across APIs (#38300) * docs: add ADR for api versioning strategy (#38304) * docs: add ADR for standardizing filtering/sorting parameters (#38303) * docs: add ADR-0029 standardized error responses decision (#38246) * docs: add ADR for merging similar endpoints (#38262) * docs: ADR for normalizing nested json apis (#38305) * docs: add separate example for input & output serializers * docs: ADR for documenting and consolidating internal MFE APIs (#38309) * docs: ADR for documenting and consolidating internal MFE APIs Define a plan to document all undocumented internal LMS APIs consumed by MFEs into stable, OpenAPI-described contracts. Introduces a consolidated config endpoint pattern with optional course/user context, authentication boundaries, and a rollout plan following OEP-21 DEPR process. * docs: add ADR for canonical MFE configuration endpoint Record that /api/frontend_site_config/v1/ is the canonical endpoint for MFE/front-end runtime configuration (frontend-base SiteConfig, OEP-65) and that /api/mfe_config/v1 is legacy, on the DEPR path tracked in #37255 and added, and that user-context data (roles, permissions) belongs on resource-oriented endpoints rather than on a configuration payload. Documentation/schema coverage is deferred to the API Documentation & Schema Coverage ADR (#38189). Partially supersedes ADR 0001 (MFE Config API). Part of FC-0118 Open edX REST API standardization (#38137). Refs #38280 * docs: add ADR for standardizing authentication patterns (#38301) * docs: add ADR for standardizing authentication patterns * docs: resolve confusion & update the ADR based on OEP-0042 * docs: support multiple valid auth schemes & deprecate BearerAuthentication * docs: change wording for decisions a bit. * docs: add real examples in accordance with our updated decisions * docs: sync ADR with edx-drf-extensions issue 284 openedx/edx-drf-extensions#284 * docs: make doc more explicit & address comments * docs: move Bearer auth depr plan out of ADR Move BearerAuthentication depr plan out of this doc So that it resides in single place i.e. to its deprecation ticket. * docs: add a pointer file in oauth_dispatch for this ADR * docs: make decision more clear * docs: make authentication_classes usage more clearer * docs: adress the comment related to session authentication * chore: correct file number w.r.t order of the ADRs --------- Co-authored-by: Muhammad Faraz Maqsood <faraz.maqsood@A006-01130.local> Co-authored-by: Taimoor Ahmed <68893403+taimoor-ahmed-1@users.noreply.github.com> Co-authored-by: Taimoor Ahmed <taimoor.ahmed@A006-01711.local> Co-authored-by: Robert Raposa <rraposa@edx.org> Co-authored-by: Abdul Muqadim <abdul.muqadim@A006-01811.local> Co-authored-by: Abdul Muqadim <abdul.muqadim@192.168.1.7> Co-authored-by: Abdul-Muqadim-Arbisoft <139064778+Abdul-Muqadim-Arbisoft@users.noreply.github.com>
5 participants
Adds ADR proposing the approach for documenting and consolidating undocumented internal LMS APIs that MFEs depend on into stable, OpenAPI-described contracts.
Currently, MFEs consume internal endpoints with no schema, versioning,or deprecation guarantees, leading to silent runtime breakages on backend refactors and blocking external integrators. This ADR documents the decision to consolidate MFE configuration into a single documented endpoint (/api/mfe_config/v1/), extend it with optional course_id and user-role context behind authentication boundaries, and deprecate ad-hoc internal endpoints following the OEP-21 DEPR process with a 6-month compatibility window.
issue: #38280