Description
Within the PP3.5 workstream, we would like to update the routing for Wikimedia APIs to go through a canonical {projectHost}/api/* pathway. We want to confirm whether MediaWiki's existing index.php rewrite pattern in Apache can be reused for API routing, since this would let us support a canonical /api/ base URL without pushing all rerouting logic into the REST Gateway, and ensuring that internal requests that circumvent the REST Gateway are also handled correctly.
Changing the base URL isn't a simple string swap. The concept of the /api/ routing will be checked at the Gateway, yet MediaWiki generates and responds to direct requests on its own, meaning that any changes to the baseUrl may have cascading impacts, particularly for internal calls that do not go through the REST Gateway. MediaWiki also generates links to other endpoints within its own responses (eg: pagination, related resources), so every module needs to know which canonical URL prefix to use when it builds those links, and be able to respond correctly to requests with either /rest|api.php/ or /api/ baseUrls.
In a similar vein, MediaWiki cannot fully resolve page titles on its own, particularly if they have changed. Apache handles that rewrite before a request ever reaches index.php for remapping page titles, and the recommendation is to mimic that same pattern for /api/ → rest.php. The purpose of this ticket is to investigate the viability of that approach and make a recommendation for how to proceed with canonical API routing.
Conditions of acceptance
- Document how index.php's Apache-level rewrite currently works
- Determine if we can handle an /api|rest.php/ --> /api/ redirect through Apache, similar to how index.php works for page titles.
- Identify what breaks (if anything) for internal callers that bypass the REST Gateway
- Recommendation: does the new prefix need global MediaWiki awareness, or can it be scoped per module?
- Update excalidraw (or other) diagram as needed to represent the design moving forward
- Update PP3.5 team about findings, so that we can decide how to proceed with the remaining canonical routing work
- [Optional] Grab time with Tim S for background on how the current API framework evolved, to make sure canonical routing decisions account for historical constraints that may not be obvious from current documentation. --> Let Halley know if you want to set up and/or participate in this
Implementation details
