[FC-0118] docs: ADR for documenting and consolidating internal MFE APIs#38309
Conversation
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.
Abdul-Muqadim-Arbisoft
requested review from
Faraz32123,
feanil and
taimoor-ahmed-1
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?
| 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! |
4 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