5.2.8: [API Module Creation] If we create dedicated API modules for all API extensions and self-contained functionality within MediaWiki Core, we will enable enforcement for higher quality documentation with independent management and versioning.

Background

MediaWiki APIs span MediaWiki Core capabilities and any registered MediaWiki extensions that surface custom APIs. Extensions are registered through MediaWiki Core. Once registered, they are effectively treated as part of the monolith, with highly manual enforcement of expectations for URL structure and versioning. As a result, the specific versioning of the different APIs is muddied and inconsistent across the spec, URL pathing, and the API itself. For example, if a single endpoint is subjected to a breaking change, it is often unclear if and where the version change should be implemented across unrelated capabilities.

API Modules
Earlier in 2024, the MediaWiki Interfaces team introduced the concept of API Modules. Each API module is intended to define a set of related endpoints that serve a common capability. In most cases, this also creates clearer boundary lines for ownership and maintenance purposes. With API modules, different teams are expected to own their respective API definitions in addition to the underlying business logic of the API.

This structure not only enables teams to operate independently, but also creates an ecosystem with cleaner ownership for the full technical capabilities. This means that as MediaWiki Interfaces transitions to become more of an API Platform team, we will have better systems and ownership models in place when it comes time for enforcing quality and policy standards across the Wikimedia API ecosystem.

Problem statement

Endpoints for MediaWIki Core and enabled extensions currently present themselves as a singular API, which is difficult to maintain and version, in addition to being confusing for end users due to inconsistencies across naming conventions, response code utilization, and object models. To build towards more consistent and well governed systems, we need clearer ownership and versioning boundaries across different APIs. API modules will allow us to create clearer boundaries through well defined contexts and independently manageable API definitions, and the separation between Core and each enabled extension offers is a great first candidate since the boundaries of ownership and responsibility are already relatively clean.

Impacted users
API Authors will face the most impact. As we technically introduce API modules, there is an implicit transition in ownership where API authors will now be responsible for following standards set by the MediaWiki Interfaces team for things like spec generation quality and test coverage. Simply separating out API modules is the first step in that direction, with an assumption that API authors will take on more ownership over spec content and automated testing.

API users will also be impacted in a more minor way — as we create API modules, we intend to surface them as separate APIs from a documentation and REST Sandbox perspective. Users who are accustomed to the current approach of having all of the endpoints in a single list may find the changes confusing. There is also a risk that the boundaries of related capabilities within a given module may not match the mental model for all consumers.

Scope

• Create dedicated API modules for at least 1 extension API commonly enabled in standard Wikimedia configurations.
  • [Stretch]: Create additional modules for most commonly enabled, self-contained extension APIs.
  • Capture any extensions that do not fit the desired pattern or require additional follow-up with owning teams.
• Ensure that API Modules (MW Core; Tokens) owned by the MediaWiki Interfaces team meet all expected and enforced standards.
• Experiment with creating a new module for Access Tokens, including improving CSRF token management and improved endpoints for OAuth token management.
• [Stretch] Experiment with audience designations within API modules.

Stretch Goals
While the main focus of this work is separating out extensions into API modules, there is a parallel need to introduce audience based access control to the existing APIs. Specifically, where APIs are currently defined as Internal or Private in documentation today, we would like to start introducing actual programmatic controls for these designations. If time allows, we will explore what audience means for module definitions, such as what it means for the visibility of the resulting specs and documentation. Introducing audience concepts to the modules will not actually enforce access control, but will instead provide the foundation for defining different audience types that can then be leveraged by downstream processes to change access models and/or endpoint behavior accordingly.

Out of Scope
We do not expect all teams to own their own modules at this time, nor do we expect the owning teams to fully meet the emerging API Platform standards. The main focus of this work is to split the existing APIs into modules, with follow ups expected to raise the bar on quality and content for the registered APIs.

Expected Outcomes

• All extensions are presented as one or more independent API module, instead of being presented within the scope of the MediaWiki REST API. This will set the foundation for distributed ownership of the individual API capabilities.
• There will be a clearer split between API Platform frameworks and foundational capabilities, vs the APIs that adopt them. By introducing this pattern of self-contained capabilities, we make the boundaries of ownership much cleaner.

Known risks & limitations

• Some Extension APIs do not have versions present in the routes. We will need to decide how to handle those cases, such as if we want to introduce versioning and reroute them, or if we allow them to exist unversioned for the time being.
• There are no clear domain boundaries within MediaWiki Core itself. An early attempt was made to present a 'content' module, but it was never fully released due to debate and concern over the scope of that module. We have several sets of endpoints that could be presented as related within a specific module, but we will need to do some experimentation with current groupings and presentation options.
  • Mitigation: We can experiment with module style groupings through the use of Tags within the OpenAPI spec. This will allow us to present different grouping options to the community and get feedback before the specific modules are locked in stone.
• Work will be happening simultaneously within the MediaWiki API Handler to improve distributed API registration and spec creation workflows. We expect the overlap to be minimal and manageable since this body of work focuses on module definitions instead of the specific API definitions, but it is a concern for work between the two initiatives.

Related Work
Module creation is related (and likely predecessor) to work for standardizing API routing and enforcing any type of access control for specific endpoint groups.

Dependencies
There are no immediate dependencies for this work.

Next steps

Once this work is complete, we will begin a handful of follow up initiatives:
Engaging with API module owners to improve the quality, coverage, and consistency of their APIs
Begin programmatic enforcement of audience based access control

Deadline
This work is committed for FY24/25 Q3; this means we expect it to be completed before the end of March 2025.