⚓ T414470 Create the first extension MW REST API module
Page Menu
Phabricator
Create Task
Maniphest
T414470
Create the first extension MW REST API module
Closed, Resolved
Public
8 Estimated Story Points
Actions
Edit Task
Edit Related Tasks...
Create Subtask
Edit Parent Tasks
Edit Subtasks
Merge Duplicates In
Close As Duplicate
Edit Related Objects...
Edit Commits
Edit Mocks
Mute Notifications
Protect as security issue
Assigned To
aaron
Authored By
HCoplin-WMF
Jan 13 2026, 2:40 PM
2026-01-13 14:40:03 (UTC+0)
Tags
OKR-Work
(Backlog)
MediaWiki-REST-API
(Backlog)
MW-Interfaces-Team (MWI-Sprint-28 (2026-02-24 to 2026-03-10))
(Demo Ready!)
MW-1.46-notes (1.46.0-wmf.19; 2026-03-10)
GrowthExperiments
(Backlog)
Referenced Files
None
Subscribers
Aklapper
BPirkle
HCoplin-WMF
OWresch-WMF
Description
Description
To promote MW REST API API module creation, we need to have an initial example. Going through the extension module creation process ourselves will also highlight opportunities to make the configuration process easier for API owning teams.
NOTE:
Which extension module is selected depends on:
Conditions of acceptance
Migrate at least one extension into a dedicated module (proposed, based on
T414469: [SPIKE] Determine the most heavily installed and used extensions across Wikimedia installations with REST endpoints
; pending feedback on additional audience modules) extension to be its own module.
Module appears in the discovery doc
Module appears in the the REST Sandbox (within the dropdown, and with docs when selected)
Lightly document the current set up process. Assume that this artifact is predominately for MediaWiki Interfaces review and utilization (for now).
Identify pain points in the configuration and deployment process, as it exists today.
Proposed improvements for pain points.
Demo current setup process with the MWI team.
Review identified pain points and potential fixes with the MWI team.
Create follow up tasks as needed, once we are aligned on the problems and proposed solutions.
Out of scope
For now, do not worry about making the spec fully linter compliant. We can have a follow up task to raise the bar on the quality of the generated spec, likely in partnership with the owning team.
Details
Related Changes in Gerrit:
Subject
Repo
Branch
Lines +/-
Remove redundant flat REST routes (e.g. "RestRoutes")
mediawiki/extensions/GrowthExperiments
master
+0
-95
Add growthexperiments.v0 to $wgRestSandboxSpecs
operations/mediawiki-config
master
+7
-0
Tweak rest-module-growthexperiments.v0-title for consistency
mediawiki/extensions/GrowthExperiments
master
+1
-1
Introduce a REST module for /growthexperiments/v0 endpoints
mediawiki/extensions/GrowthExperiments
master
+182
-1
Customize query in gerrit
Related Objects
Search...
Task Graph
Mentions
Status
Subtype
Assigned
Task
Open
BPirkle
T413439
[Hypothesis] 5.2.8: API Module Creation
Open
BPirkle
T413440
[5.2.8 Epic]: Create dedicated API modules extension APIs
Resolved
aaron
T414470
Create the first extension MW REST API module
Mentioned In
T419545: Enable "Attribution API (beta)" in all REST Sandboxes
T418821: Create a mediawiki.org page about migrating extensions to from flat REST routes to modules
Mentioned Here
T409517: REST: API modules can be suppressed/opt-out of spec generation
T414469: [SPIKE] Determine the most heavily installed and used extensions across Wikimedia installations with REST endpoints
Event Timeline
HCoplin-WMF
created this task.
Jan 13 2026, 2:40 PM
2026-01-13 14:40:03 (UTC+0)
HCoplin-WMF
removed
BPirkle
as the assignee of this task.
Jan 13 2026, 2:47 PM
2026-01-13 14:47:59 (UTC+0)
HCoplin-WMF
updated the task description.
(Show Details)
HCoplin-WMF
edited projects, added
MW-Interfaces-Team
MediaWiki-REST-API
; removed
Epic
[MWI] FY2025-26 Q3
MW-Interfaces-Team (MWI-Roadmap)
HCoplin-WMF
added a subscriber:
BPirkle
BPirkle
renamed this task from
Create the first extension API module
to
Create the first extension MW REST API module
Jan 13 2026, 2:51 PM
2026-01-13 14:51:27 (UTC+0)
BPirkle
updated the task description.
(Show Details)
HCoplin-WMF
moved this task from
Incoming (Needs Triage)
to
To Refine
on the
MW-Interfaces-Team
board.
Jan 13 2026, 3:42 PM
2026-01-13 15:42:55 (UTC+0)
HCoplin-WMF
updated the task description.
(Show Details)
Jan 27 2026, 2:59 PM
2026-01-27 14:59:44 (UTC+0)
HCoplin-WMF
updated the task description.
(Show Details)
Jan 27 2026, 3:05 PM
2026-01-27 15:05:51 (UTC+0)
HCoplin-WMF
moved this task from
To Refine
to
MWI-Sprint-26 (2026-01-27 to 2026-02-10)
on the
MW-Interfaces-Team
board.
Jan 27 2026, 3:54 PM
2026-01-27 15:54:04 (UTC+0)
HCoplin-WMF
edited projects, added
MW-Interfaces-Team (MWI-Sprint-26 (2026-01-27 to 2026-02-10))
; removed
MW-Interfaces-Team
HCoplin-WMF
assigned this task to
aaron
Jan 27 2026, 4:13 PM
2026-01-27 16:13:06 (UTC+0)
HCoplin-WMF
triaged this task as
High
priority.
OWresch-WMF
set the point value for this task to
Jan 27 2026, 4:19 PM
2026-01-27 16:19:46 (UTC+0)
gerritbot
added a comment.
Feb 4 2026, 5:12 AM
2026-02-04 05:12:23 (UTC+0)
Comment Actions
Change #1236409 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):
[mediawiki/extensions/GrowthExperiments@master] [WIP] Introduce a REST module for /growthexperiments/v0 endpoints
gerritbot
added a project:
Patch-For-Review
Feb 4 2026, 5:12 AM
2026-02-04 05:12:24 (UTC+0)
aaron
moved this task from
Committed
to
In Progress
on the
MW-Interfaces-Team (MWI-Sprint-26 (2026-01-27 to 2026-02-10))
board.
Feb 6 2026, 1:05 AM
2026-02-06 01:05:29 (UTC+0)
OWresch-WMF
edited projects, added
MW-Interfaces-Team (MWI-Sprint-27 (2026-02-10 to 2026-02-24))
; removed
MW-Interfaces-Team (MWI-Sprint-26 (2026-01-27 to 2026-02-10))
Feb 11 2026, 9:58 AM
2026-02-11 09:58:26 (UTC+0)
OWresch-WMF
moved this task from
Committed
to
In Progress
on the
MW-Interfaces-Team (MWI-Sprint-27 (2026-02-10 to 2026-02-24))
board.
gerritbot
added a comment.
Feb 23 2026, 9:37 AM
2026-02-23 09:37:21 (UTC+0)
Comment Actions
Change #1236409
merged
by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Introduce a REST module for /growthexperiments/v0 endpoints
ReleaseTaggerBot
added a project:
MW-1.46-notes (1.46.0-wmf.17; 2026-02-24)
Feb 23 2026, 10:00 AM
2026-02-23 10:00:53 (UTC+0)
Maintenance_bot
removed a project:
Patch-For-Review
Feb 23 2026, 10:31 AM
2026-02-23 10:31:23 (UTC+0)
gerritbot
added a comment.
Feb 24 2026, 12:15 AM
2026-02-24 00:15:20 (UTC+0)
Comment Actions
Change #1242538 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):
[mediawiki/extensions/GrowthExperiments@master] Tweak rest-module-growthexperiments.v0-title for consistency
gerritbot
added a project:
Patch-For-Review
Feb 24 2026, 12:15 AM
2026-02-24 00:15:21 (UTC+0)
gerritbot
added a comment.
Feb 24 2026, 4:15 AM
2026-02-24 04:15:15 (UTC+0)
Comment Actions
Change #1242613 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):
[operations/mediawiki-config@master] [DNM] Add growthexperiments.v0 to $wgRestSandboxSpecs
gerritbot
added a comment.
Feb 24 2026, 5:49 AM
2026-02-24 05:49:33 (UTC+0)
Comment Actions
Change #1242743 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):
[mediawiki/extensions/GrowthExperiments@master] [DNM] Remove redundant flat REST routes (e.g. "RestRoutes")
aaron
moved this task from
In Progress
to
Code Review
on the
MW-Interfaces-Team (MWI-Sprint-27 (2026-02-10 to 2026-02-24))
board.
Feb 24 2026, 3:51 PM
2026-02-24 15:51:01 (UTC+0)
gerritbot
added a comment.
Feb 24 2026, 5:29 PM
2026-02-24 17:29:05 (UTC+0)
Comment Actions
Change #1242538
merged
by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Tweak rest-module-growthexperiments.v0-title for consistency
ReleaseTaggerBot
edited projects, added
MW-1.46-notes (1.46.0-wmf.18; 2026-03-03)
; removed
MW-1.46-notes (1.46.0-wmf.17; 2026-02-24)
Feb 24 2026, 6:00 PM
2026-02-24 18:00:56 (UTC+0)
aaron
added a comment.
Edited
Feb 25 2026, 1:53 AM
2026-02-25 01:53:03 (UTC+0)
Comment Actions
Here are the current generic steps I'm going through with GrowthExperiements:
Make sure you locally enable DevelopmentSettings.php so that specs endpoints and the Special:RestSandbox special page work. The old flat routes should listed at
rest.php/specs/v0/module/-
Locally, the existing unit tests and api-testing integration tests should work locally as a reference point. Adds some if needed, making a stand-alone patch to base the actual module patches on.
Look at the extension's current flat routes files (referenced from "RestRoutes" in extension.json). Find the path prefix, in the form of "/
Make a patch adding the module definition file named "
"RestModuleFiles": [ "
(e.g. use "includes/Rest/growthexperiments.v0.json"). Leave the old "RestRoutes" redundant values in place, the module routes will take precedence.
Make sure the file defines all the routes and i18n- message keys and looks like it meets the newest mw-api schema under includes/docs/rest/ (e.g. "mw-api-1.1.json" at the time of this writing). See includes/Rest/growthexperiments.v0.json" from GrowthExperiments as an example.
Make sure that the old flat routes are still listed at
rest.php/specs/v0/module/-
Make sure the new specs appear at
rest.php/specs/v0/discovery
Make sure that the new specs appear at
rest.php/specs/v0/module/
(e.g. "rest.php/specs/v0/module/growthexperiments/v0"). This is the module's API spec (not to be confused with the "module spec" mentioned above). Create any messages that appear as placeholders (make the en.json and qqq.json files and update "MessagesDirs" in extension.json as needed). Make sure that the
'rest-module-
message, in English, says something like "Such-and-such API" (e.g. "Growth experiments API"). It's probably a good idea to use a Rest/ subdirectory for such messages instead of mixing them with a huge grab-bag of messages for the extension. You might need to clear APCu or run rebuildLocalisationCache.php after adding new messages.
Locally, set $wgRestSandboxSpecs["
"$wgScriptPath/rest.php/specs/v0/module/
and 'msg' to
'rest-module-
. The Special:RestSandbox page should show a working dropdown for the new module.
The phpunit and api-testing tests should pass, since they map to handlers doing the same thing. Note that core will structure test the new module definition files for validity in testModuleDefinitionFiles.
You can paste the pretty-printed output of
rest.php/specs/v0/module/
into
to lightly validate the output. You can also paste it into
to check for our org-specific rules. Many of the issues might simply carry over from the original flat module API specs, and they might be numerous...this is best left as separate follow-up work.
Make a similar CommonSettings.php patch in the mediawiki-config repo that sets the wgRestSandboxSpecs key right after the relevant wfLoadExtension() call. This will add a dropdown for the module at the RestSandbox page, with the flat routes still remaining. Once the flat routes eventually get removed, their specs will disappear. Merge it only after the above extension patches get merged and the deploy train looks stable (a train rollback will make the RestSandbox page show load errors since the module spec URL will fail to load).
Create a patch to remove the old flat routes from the extension. Merge it only after the above CommonSettings.php patch is merged.
The main pain points seem to be:
The song and dace of having to do a config change since modules do not get pulled into the RestSandbox automagically. We want to avoid having the endpoints disappear completely from the RestSandbox but also don't want RestSandbox load errors because the module isn't enabled yet. This forces multiple extension commits and a backport deploy, which adds delay, complication, and similar code fragments scattered through config that each "know" something about the extensions moduleId.
A more clever way could involve a more conditional config patch that only updates the sandbox specs if the extension is on a version having the module definition file. Within InitialiseSettings.php/CommonsSettings.php, it's too early to use stuff like
extension version checks
or checking a new constant defined by the extension, as Setup.php has not yet reached
ExtensionRegistry::getInstance()->finish()
. You could have something in the block with the relevant wfLoadExtension() checking the existence of
"$wgExtensionDirectory/my_extension/src/Rest/my_module.v1.json"
, but that seems ugly and would break if the json file moved. Also, ExtensionProcessor does not support a 'RestSandboxSpecs' field and that variable is marked as experimental anyway.
In theory, the extension.json could have "callback" set to the name of a static function that updates $wgRestSandboxSpecs (though it's still marked experimental).
The current audience proposal at
T409517#11563818
would moot this whole issue.
Having to mess around with module spec caching and localization caching.
HCoplin-WMF
edited projects, added
MW-Interfaces-Team (MWI-Sprint-28 (2026-02-24 to 2026-03-10))
; removed
MW-Interfaces-Team (MWI-Sprint-27 (2026-02-10 to 2026-02-24))
Feb 26 2026, 6:22 PM
2026-02-26 18:22:39 (UTC+0)
HCoplin-WMF
moved this task from
Committed
to
Code Review
on the
MW-Interfaces-Team (MWI-Sprint-28 (2026-02-24 to 2026-03-10))
board.
gerritbot
added a comment.
Mar 2 2026, 10:03 PM
2026-03-02 22:03:03 (UTC+0)
Comment Actions
Change #1242613
merged
by jenkins-bot:
[operations/mediawiki-config@master] Add growthexperiments.v0 to $wgRestSandboxSpecs
Stashbot
added a comment.
Mar 2 2026, 10:03 PM
2026-03-02 22:03:23 (UTC+0)
Comment Actions
Mentioned in SAL (#wikimedia-operations)
[2026-03-02T22:03:22Z]
T414470
)]]
Stashbot
added a comment.
Mar 2 2026, 10:05 PM
2026-03-02 22:05:12 (UTC+0)
Comment Actions
Mentioned in SAL (#wikimedia-operations)
[2026-03-02T22:05:11Z]
T414470
)]] synced to the testservers (see
). Changes can now be verified there.
Stashbot
added a comment.
Mar 2 2026, 10:10 PM
2026-03-02 22:10:02 (UTC+0)
Comment Actions
Mentioned in SAL (#wikimedia-operations)
[2026-03-02T22:10:02Z]
T414470
)]] (duration: 06m 39s)
aaron
added a comment.
Edited
Mar 3 2026, 2:09 AM
2026-03-03 02:09:19 (UTC+0)
Comment Actions
By making the CommonSettings.php patch in mediawiki-config similar to
, a single extension repo patch can be made to migrate the extension from flat routes to a module, instead of two. The config patch should be deployed first, with the extension patch riding the train later.
The new process becomes:
Make sure you locally enable DevelopmentSettings.php so that specs endpoints and the Special:RestSandbox special page work. The old flat routes should listed at
rest.php/specs/v0/module/-
Locally, the existing unit tests and api-testing integration tests should work locally as a reference point. Adds some tests if needed, making a stand-alone patch to base the actual module patches on.
Look at the extension's current flat routes files (referenced from "RestRoutes" in extension.json). Find the path prefix, in the form of "/
Make a patch adding the module definition file named "
"RestModuleFiles": [ "
(e.g. use "includes/Rest/growthexperiments.v0.json"). Remove the old "RestRoutes" redundant values.
Make sure the file defines all the routes and i18n- message keys and looks like it meets the newest mw-api schema under includes/docs/rest/ (e.g. "mw-api-1.1.json" at the time of this writing). See includes/Rest/growthexperiments.v0.json" from GrowthExperiments as an example.
Make sure that the old flat routes are no longer listed at
rest.php/specs/v0/module/-
Make sure the new specs appear at
rest.php/specs/v0/discovery
Make sure that the new specs appear at
rest.php/specs/v0/module/
(e.g. "rest.php/specs/v0/module/growthexperiments/v0"). This is the module's API spec (not to be confused with the "module spec" mentioned above). Create any messages that appear as placeholders (make the en.json and qqq.json files and update "MessagesDirs" in extension.json as needed). Make sure that the
'rest-module-
message, in English, says something like "Such-and-such API" (e.g. "Growth experiments API"). It's probably a good idea to use a Rest/ subdirectory for such messages instead of mixing them with a huge grab-bag of messages for the extension. You might need to clear APCu or run rebuildLocalisationCache.php after adding new messages.
Locally, to your config, add code that checks is_file() on the new module definition file to set $wgRestSandboxSpecs["
"$wgExtensionDirectory/
. Here is an
example patch
. The Special:RestSandbox page should show a working dropdown for the new module.
The phpunit and api-testing tests should pass, since they map to handlers doing the same thing. Note that core will structure test the new module definition files for validity in testModuleDefinitionFiles.
You can paste the pretty-printed output of
rest.php/specs/v0/module/
into
to lightly validate the output. You can also paste it into
to check for our org-specific rules. Many of the issues might simply carry over from the original flat module API specs, and they might be numerous...this is best left as separate follow-up work.
Make a similar CommonSettings.php patch in the mediawiki-config repo that conditionally sets the wgRestSandboxSpecs key right after the relevant wfLoadExtension() call. Once the module patch is deployed, the flat route specs will disappear and get replaced by the module specs. Until then, the flat routes will remain in the REST sandbox.
Deploy the mediawiki-config patch before the extension patch gets rolled out so the routes never go missing from the sandbox. It might help to mark the extension patch as DNM until the config patch is merged.
aaron
updated the task description.
(Show Details)
Mar 3 2026, 2:10 AM
2026-03-03 02:10:07 (UTC+0)
aaron
moved this task from
Code Review
to
Demo Ready!
on the
MW-Interfaces-Team (MWI-Sprint-28 (2026-02-24 to 2026-03-10))
board.
Mar 3 2026, 2:26 AM
2026-03-03 02:26:04 (UTC+0)
aaron
mentioned this in
T418821: Create a mediawiki.org page about migrating extensions to from flat REST routes to modules
Mar 3 2026, 2:28 AM
2026-03-03 02:28:29 (UTC+0)
gerritbot
added a comment.
Mar 9 2026, 6:56 PM
2026-03-09 18:56:52 (UTC+0)
Comment Actions
Change #1242743
merged
by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Remove redundant flat REST routes (e.g. "RestRoutes")
ReleaseTaggerBot
edited projects, added
MW-1.46-notes (1.46.0-wmf.19; 2026-03-10)
; removed
MW-1.46-notes (1.46.0-wmf.18; 2026-03-03)
Mar 9 2026, 7:00 PM
2026-03-09 19:00:28 (UTC+0)
Maintenance_bot
removed a project:
Patch-For-Review
Mar 9 2026, 7:32 PM
2026-03-09 19:32:22 (UTC+0)
HCoplin-WMF
closed this task as
Resolved
Mar 10 2026, 7:06 PM
2026-03-10 19:06:18 (UTC+0)
HCoplin-WMF
mentioned this in
T419545: Enable "Attribution API (beta)" in all REST Sandboxes
Mar 12 2026, 3:36 PM
2026-03-12 15:36:31 (UTC+0)
A_smart_kitten
added a project:
GrowthExperiments
Mar 13 2026, 10:16 AM
2026-03-13 10:16:48 (UTC+0)
Log In to Comment
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct.
Wikimedia Foundation
Code of Conduct
Disclaimer
CC-BY-SA
GPL
Credits
US