Page MenuHomePhabricator

Reroute /api/rest_v1 documentation to REST Sandbox
Closed, ResolvedPublic3 Estimated Story Points

Description

Description

RESTbase API documentation is hosted through RESTbase and uses SwaggerUI for visualization. Once RESTbase is fully deprecated, the API documentation will no longer be accessible on the existing URL. Earlier this year, we launched the REST Sandbox, which similarly offers SwaggerUI based API documentation as a Special page on Wikimedia projects. We are already displaying a copy of the RESTbase endpoint documentation within this page, and can therefore use it as an alternative to the existing solution following the RESTbase sunset.

Conditions of acceptance

NOTE: REST Sandboxes are not currently live across all Wikimedia projects. We will need to complete the global rollout for the sandbox to appropriately make the documentation available on all Wikimedia projects.

Event Timeline

HCoplin-WMF triaged this task as High priority.
HCoplin-WMF updated the task description. (Show Details)
HCoplin-WMF set the point value for this task to 3.

Change #1190753 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[operations/deployment-charts@master] [DNM] rest-gateway: map restbase sandbox URLs to Special:RestSandbox/wmf-restbase

https://gerrit.wikimedia.org/r/1190753

Change #1190754 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[operations/puppet@production] [DNM] rest-gateway: migrate /api/rest_v1/ (sandbox) to the rest gateway

https://gerrit.wikimedia.org/r/1190754

Note for @aaron -- please make sure that we can actually link to the right module within the sandbox. Specifically, when rerouting the RESTBase docs, we will need to select the right module from the dropdown and load it onto the page so the right docs show on redirect:

image.png (181×739 px, 20 KB)

I'm not sure if/how that is possible right now. You might want to consult with @BPirkle on it.

Once the config change to enable REST Sandbox everywhere is reviewed/approved/deployed, a relative path like /w/index.php?api=wmf-restbase&title=Special%3ARestSandbox should work on all wikis.

aaron renamed this task from [BLOCKED] Reroute /api/rest_v1 documentation to REST Sandbox to Reroute /api/rest_v1 documentation to REST Sandbox.Oct 27 2025, 4:20 PM

Change #1190753 abandoned by Aaron Schulz:

[operations/deployment-charts@master] [DNM] rest-gateway: map restbase sandbox URLs to Special:RestSandbox/wmf-restbase

Reason:

Going with https://gerrit.wikimedia.org/r/c/operations/puppet/+/1190754

https://gerrit.wikimedia.org/r/1190753

Change #1207267 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[operations/deployment-charts@master] rest-gateway: support REST sandbox requests

https://gerrit.wikimedia.org/r/1207267

Change #1219604 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[operations/puppet@production] restgateway: migrate the /api/rest_v1/ sandbox to the rest gateway

https://gerrit.wikimedia.org/r/1219604

Change #1207267 merged by jenkins-bot:

[operations/deployment-charts@master] rest-gateway: support REST sandbox requests

https://gerrit.wikimedia.org/r/1207267

Change #1220318 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/deployment-charts@master] api-gateway: Fix host_rewrite_path_regex substitution

https://gerrit.wikimedia.org/r/1220318

Change #1220318 merged by jenkins-bot:

[operations/deployment-charts@master] api-gateway: Fix host_rewrite_path_regex substitution

https://gerrit.wikimedia.org/r/1220318

Change #1219604 merged by Clément Goubert:

[operations/puppet@production] restgateway: migrate the /api/rest_v1/ sandbox to the rest gateway

https://gerrit.wikimedia.org/r/1219604

CSP breaks JS and CSS on https://wikimedia.org/api/rest_v1/

Apache rewrite-rule redirects in modules/mediawiki/templates/apache/sites/included/www.wikimedia.org.conf.erb rewrites https://www.wikimedia.org/api/rest_v1/ to https://foundation.wikimedia.org/wiki/Special:RestSandbox/wmf-restbase breaking the API def loading

This is a little much to fix in two days before the holidays, especially the apache patch, so I will revert the trafficserver patch and we will fix and ship this as soon as we're back from holiday.

Change #1220320 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/puppet@production] Revert "restgateway: migrate the /api/rest_v1/ sandbox to the rest gateway"

https://gerrit.wikimedia.org/r/1220320

Change #1220320 merged by Clément Goubert:

[operations/puppet@production] Revert "restgateway: migrate the /api/rest_v1/ sandbox to the rest gateway"

https://gerrit.wikimedia.org/r/1220320

Change #1223188 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/puppet@production] apache: Don't redirect RestSandbox on wikimedia.org

https://gerrit.wikimedia.org/r/1223188

Change #1190754 abandoned by Clément Goubert:

[operations/puppet@production] rest-gateway: migrate /api/rest_v1/ sandbox to Special:RestSandbox

Reason:

Abandoned in favour of the approach in I2db6b422eb

https://gerrit.wikimedia.org/r/1190754

Change #1223188 merged by Clément Goubert:

[operations/puppet@production] apache: Don't redirect RestSandbox on wikimedia.org

https://gerrit.wikimedia.org/r/1223188

Mentioned in SAL (#wikimedia-operations) [2026-01-06T11:20:59Z] <claime> Deploying apache config change T396807 - 1223188

So it turns out the apache change I did isn't right, I'm wondering if we shouldn't catch https://www.wikimedia.org/api/rest_v1/ in the same way we catch https://wikimedia.org/api/rest_v1/ and redirect to the page on meta.wikimedia.org, and move all of them to the mw-rest-php block to disable CSP.

I'll revert until we discuss it.

Change #1223643 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/puppet@production] Revert "apache: Don't redirect RestSandbox on wikimedia.org"

https://gerrit.wikimedia.org/r/1223643

Change #1223643 merged by Clément Goubert:

[operations/puppet@production] Revert "apache: Don't redirect RestSandbox on wikimedia.org"

https://gerrit.wikimedia.org/r/1223643

Change #1223659 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/deployment-charts@master] rest-gateway: Move REST API Sandbox to mw-rest-php

https://gerrit.wikimedia.org/r/1223659

We don't need the sandbox to work on www.wikimedia.org, just wikimedia.org. We currently use www.wikimedia.org for rest_v1-wikimedia.json, but I've been thinking about copying that file to standard-docroot and pointing the MediaWiki REST sandbox to that file on meta.wikimedia.org (then deleting the old file later). Basically, I'd like to avoid www.wikimedia.org completely.

Change #1223659 merged by jenkins-bot:

[operations/deployment-charts@master] rest-gateway: Move REST API Sandbox to mw-rest-php

https://gerrit.wikimedia.org/r/1223659

rest-gateway patch merged and deployed, I'll do the ATS change tomorrow so I can monitor.

Change #1224228 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[operations/mediawiki-config@master] Copy rest_v1-wikimedia.json to standard-docroot

https://gerrit.wikimedia.org/r/1224228

Still got some CSS issues on https://wikimedia.org/api/rest_v1/

GET	https://www.wikimedia.org/w/load.php?lang=en&modules=site.styles&only=styles&skin=vector-2022 404

The /w/load.php GET calls get 301'd to www.wikimedia.org/w/load.php, I assume because of this line in redirects.dat

rewrite>........................wikimedia.org>..................https://www.wikimedia.org

The vhost def for www.wikimedia.org is in modules/mediawiki/templates/apache/sites/included/www.wikimedia.org.conf.erb.

Confusingly it does not use mediawiki-config/docroot/mediawiki.org but mediawiki-config/docroot/wwwportal. Would it be enough to symling or copy /w/load.php to this docroot maybe?

I have to admit I'm a little lost in the metaphorical sauce of multiple redirects and can't pinpoint what I should add where. I'll ask the team.

After testing the symlink using mw-experimental, it ends up hitting missing.php

No wiki found

Sorry, we were not able to work out what wiki you were trying to view. Please specify a valid Host header.

We don't need the sandbox to work on www.wikimedia.org, just wikimedia.org. We currently use www.wikimedia.org for rest_v1-wikimedia.json, but I've been thinking about copying that file to standard-docroot and pointing the MediaWiki REST sandbox to that file on meta.wikimedia.org (then deleting the old file later). Basically, I'd like to avoid www.wikimedia.org completely.

There's no wiki associated with wikimedia.org or www.wikimedia.org, so that can't work.

Ok, I'll revert the ATS patch again

We don't need the sandbox to work on www.wikimedia.org, just wikimedia.org. We currently use www.wikimedia.org for rest_v1-wikimedia.json, but I've been thinking about copying that file to standard-docroot and pointing the MediaWiki REST sandbox to that file on meta.wikimedia.org (then deleting the old file later). Basically, I'd like to avoid www.wikimedia.org completely.

There's no wiki associated with wikimedia.org or www.wikimedia.org, so that can't work.

I wasn't talking about a fix for sandbox redirection but rather noting that https://www.wikimedia.org/api/rest_v1/ does not need to show a sandbox and also suggesting a cleanup for the json spec files, where rest_v1-wikimedia.json would be in the standard-docroot rather than wwwportal.

Yes, the main issue is that https://wikimedia.org/api/rest_v1/ cannot simply remap to the sandbox since assets using relative paths for stylesheets and load.php URLs are not going to work (absolute ones can work if CSP does not get in the way). I think https://wikimedia.org/api/rest_v1/ needs to actually 301/308 redirect to the metawiki sandbox page, perhaps via Envoy host_redirect/path_redirect directives in the gateway (instead of host_rewrite_path_regex/regex_rewrite like the last patch).

Change #1224838 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[operations/deployment-charts@master] rest-gateway: changed REST sandbox rerouting to redirection

https://gerrit.wikimedia.org/r/1224838

Change #1226288 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/puppet@production] Revert^4 "restgateway: migrate the /api/rest_v1/ sandbox to the rest gateway"

https://gerrit.wikimedia.org/r/1226288

Change #1224838 merged by jenkins-bot:

[operations/deployment-charts@master] rest-gateway: changed REST sandbox rerouting to redirection

https://gerrit.wikimedia.org/r/1224838

Change #1226291 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/deployment-charts@master] rest-gateway: Fix RedirectResponseCode value

https://gerrit.wikimedia.org/r/1226291

Change #1226291 merged by jenkins-bot:

[operations/deployment-charts@master] rest-gateway: Fix RedirectResponseCode value

https://gerrit.wikimedia.org/r/1226291

Change #1226780 had a related patch set uploaded (by Clément Goubert; author: Clément Goubert):

[operations/puppet@production] gateway-check: Document additional query parameter

https://gerrit.wikimedia.org/r/1226780

Change #1226288 merged by Clément Goubert:

[operations/puppet@production] Revert^4 "restgateway: migrate the /api/rest_v1/ sandbox to the rest gateway"

https://gerrit.wikimedia.org/r/1226288

Change #1226780 merged by Clément Goubert:

[operations/puppet@production] gateway-check: Document additional query parameter

https://gerrit.wikimedia.org/r/1226780

ATS patch redeployed, it looks ok to me, @aaron can you check and resolve if everything looks good to you?

ATS patch redeployed, it looks ok to me, @aaron can you check and resolve if everything looks good to you?

Looks fine now. Good catch with https://gerrit.wikimedia.org/r/c/operations/deployment-charts/+/1226291 :)