Page MenuHomePhabricator
Create Task
Maniphest T396805

Define static OpenAPI specs per API family for RESTbase endpoints
Closed, ResolvedPublic5 Estimated Story Points
Actions

Description

Description

RESTbase offers different configurations based on the Wikimedia project family (eg: Wiktionary, Wikipedia). To support API documentation following the RESTbase sunset, we need to have static definitions for each of these configurations, which will then be hosted through MediaWiki and used for API reference documentation.

Conditions of acceptance

  • Define a static OpenAPI spec for each API family.
  • Provide the logic/mapping for which spec should be used with each project family.
  • Review and hand off to MWI for implementation.

Details

Other Assignee
MSantos
Related Changes in Gerrit:
Show related patches Customize query in gerrit

Related Objects
Search...

Event Timeline

HCoplin-WMF created this task.Jun 12 2025, 9:54 PM
HCoplin-WMF mentioned this in T396806: Return different OpenAPI spec definitions through the REST Gateway.Jun 12 2025, 10:02 PM
hnowlan subscribed.Jun 13 2025, 3:31 PM
HCoplin-WMF mentioned this in T397203: [SPIKE] Propose a location for hosting RESTBase OpenAPI spec definitions .Jun 17 2025, 2:27 PM
HCoplin-WMF moved this task from Incoming (Needs Triage) to Radar (other teams work) on the MW-Interfaces-Team board.Jun 18 2025, 1:00 PM
HCoplin-WMF assigned this task to Jgiannelos.Jun 30 2025, 1:09 PM
HCoplin-WMF added a subscriber: MSantos.
MSantos edited projects, added Content-Transform-Team (Work In Progress); removed Content-Transform-Team.Jul 3 2025, 2:20 PM
Jgiannelos removed Jgiannelos as the assignee of this task.Jul 3 2025, 2:53 PM
Jgiannelos subscribed.
HCoplin-WMF assigned this task to MSantos.Jul 7 2025, 12:12 PM
HCoplin-WMF updated the task description. (Show Details)
HCoplin-WMF mentioned this in T398819: Host and return different versions of RESTBase OpenAPI specs from MediaWiki.Jul 7 2025, 12:24 PM
HCoplin-WMF moved this task from Radar (other teams work) to Next Up on the MW-Interfaces-Team board.Jul 16 2025, 3:12 PM

MWI can self-serve pulling the specs using the ?spec endpoint. List of projects can be found:

MSantos added a comment.Jul 16 2025, 5:09 PM

The source of truth will always be the restbase/deploy or restbase codebases for the detailed definition.

Here are the various permutations of the OpenAPI specs:

There are some access to the AQS 2.0 endpoints (I believe) to the Wikimedia.org domain that is not registered in the API spec, so I assume this somehow a side-effect of migrating things over to REST Gateway cc/ @hnowlan.

HCoplin-WMF moved this task from Next Up to Radar (other teams work) on the MW-Interfaces-Team board.Jul 29 2025, 3:42 PM
MSantos moved this task from Backlog to In Progress on the Content-Transform-Team (Work In Progress) board.Sep 4 2025, 2:22 PM
gerritbot added a comment.Sep 4 2025, 5:37 PM

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

[operations/mediawiki-config@master] Add restbase spec JSON files to which /rest_v1/?spec can be routed

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

gerritbot added a project: Patch-For-Review.Sep 4 2025, 5:37 PM
aaron claimed this task.Sep 15 2025, 4:31 PM
aaron updated Other Assignee, added: MSantos.

@MSantos Assigning this to myself since I made the patches for the json files. I do need review/merge though :)

gerritbot added a comment.Sep 17 2025, 9:40 PM

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

[operations/puppet@production] [DNM] Route "/api/rest_v1/?spec" requests to the rest gateway

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

gerritbot added a comment.Sep 17 2025, 9:40 PM

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

[operations/deployment-charts@master] [DNM] Route old /api/rest_v1/?specs endpoints to static JSON files

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

cscott removed a project: Content-Transform-Team (Work In Progress).Sep 22 2025, 3:20 PM
gerritbot added a comment.Sep 23 2025, 6:43 PM

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

[operations/mediawiki-config@master] Switch wgRestSandboxSpecs wmf-restbase entry on testwiki to the static specs

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

gerritbot added a comment.Sep 23 2025, 6:43 PM

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

[operations/mediawiki-config@master] Switch wgRestSandboxSpecs wmf-restbase entry to the static specs everywhere

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

gerritbot added a comment.Oct 7 2025, 8:48 PM

Change #1175942 merged by jenkins-bot:

[operations/mediawiki-config@master] Add restbase spec JSON files to which /rest_v1/?spec can be routed

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

Stashbot added a comment.Oct 7 2025, 8:48 PM

Mentioned in SAL (#wikimedia-operations) [2025-10-07T20:48:42Z] <aaron@deploy2002> Started scap sync-world: Backport for [[gerrit:1175942|Add restbase spec JSON files to which /rest_v1/?spec can be routed (T397203 T396805)]]

Stashbot added a comment.Oct 7 2025, 8:53 PM

Mentioned in SAL (#wikimedia-operations) [2025-10-07T20:53:06Z] <aaron@deploy2002> aaron: Backport for [[gerrit:1175942|Add restbase spec JSON files to which /rest_v1/?spec can be routed (T397203 T396805)]] synced to the testservers (see https://wikitech.wikimedia.org/wiki/Mwdebug). Changes can now be verified there.

Stashbot added a comment.Oct 7 2025, 8:58 PM

Mentioned in SAL (#wikimedia-operations) [2025-10-07T20:58:49Z] <aaron@deploy2002> Finished scap sync-world: Backport for [[gerrit:1175942|Add restbase spec JSON files to which /rest_v1/?spec can be routed (T397203 T396805)]] (duration: 10m 13s)

BPirkle mentioned this in T389409: Release REST API Sandbox on all remaining wikis.Oct 15 2025, 4:17 PM
gerritbot added a comment.Oct 17 2025, 8:44 AM

Change #1177514 merged by jenkins-bot:

[operations/deployment-charts@master] Route old /api/rest_v1/?specs endpoints to static JSON files

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

gerritbot added a comment.Oct 17 2025, 10:05 AM

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

[operations/deployment-charts@master] Route old /api/rest_v1/?specs endpoints to static JSON files

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

gerritbot added a comment.Oct 17 2025, 10:34 AM

Change #1196875 merged by jenkins-bot:

[operations/deployment-charts@master] Route old /api/rest_v1/?specs endpoints to static JSON files

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

Clement_Goubert subscribed.Oct 17 2025, 11:10 AM

Quoting my own post from the wrong task

In T397203#11284585, @Clement_Goubert wrote:

I merged this in staging this morning, and for some yet unknown reason, the regexes are not matching and envoy returns 404s because of no route match.
We will investigate further.

cgoubert@deploy2002:~$ curl -v -k -H 'Host: wikimedia.org' https://staging.svc.eqiad.wmnet:4113/wikimedia.org/v1/?spec 
[...]
> GET /wikimedia.org/v1/?spec HTTP/1.1
> Host: wikimedia.org
> User-Agent: curl/7.74.0
> Accept: */*
> 
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* old SSL session ID is stale, removing
* Mark bundle as not supporting multiuse
< HTTP/1.1 404 Not Found
< content-length: 42
< content-type: application/json
< content-security-policy: default-src 'none'; frame-ancestors 'none'
< date: Fri, 17 Oct 2025 09:34:48 GMT
< server: envoy
< 
{"httpReason":"Not Found","httpCode":404}
[2025-10-17 09:29:39.342][35][debug][conn_handler] [source/common/listener_manager/active_tcp_listener.cc:160] [Tags: "ConnectionId":"2"] new 
connection from 10.2.2.69:58598
[2025-10-17 09:29:39.387][35][debug][http] [source/common/http/conn_manager_impl.cc:393] [Tags: "ConnectionId":"2"] new stream
[2025-10-17 09:29:39.387][35][debug][http] [source/common/http/conn_manager_impl.cc:1192] [Tags: "ConnectionId":"2","StreamId":"17662462863721
800510"] request headers complete (end_stream=true):
':authority', 'wikimedia.org'
':path', '/wikimedia.org/v1/?spec'
':method', 'GET'
'user-agent', 'curl/7.74.0'
'accept', '*/*'

[2025-10-17 09:29:39.387][35][debug][http] [source/common/http/conn_manager_impl.cc:1175] [Tags: "ConnectionId":"2","StreamId":"17662462863721800510"] request end stream
[2025-10-17 09:29:39.387][35][debug][connection] [./source/common/network/connection_impl.h:98] [Tags: "ConnectionId":"2"] current connecting state: false
[2025-10-17 09:29:39.388][35][debug][router] [source/common/router/config_impl.cc:1856] route was resolved but final route list did not match incoming request
[2025-10-17 09:29:39.388][35][debug][router] [source/common/router/router.cc:446] [Tags: "ConnectionId":"2","StreamId":"17662462863721800510"] no route match for URL '/wikimedia.org/v1/?spec'
[2025-10-17 09:29:39.388][35][debug][http] [source/common/http/filter_manager.cc:1015] [Tags: "ConnectionId":"2","StreamId":"17662462863721800510"] Preparing local reply with details route_not_found
[2025-10-17 09:29:39.388][35][debug][http] [source/common/http/filter_manager.cc:1057] [Tags: "ConnectionId":"2","StreamId":"17662462863721800510"] Executing sending local reply.
[2025-10-17 09:29:39.388][35][debug][lua] [source/extensions/filters/common/lua/lua.cc:39] coroutine finished
[2025-10-17 09:29:39.388][35][debug][http] [source/common/http/conn_manager_impl.cc:1869] [Tags: "ConnectionId":"2","StreamId":"17662462863721800510"] encoding headers via codec (end_stream=false):
':status', '404'
'content-length', '42'
'content-type', 'application/json'
'content-security-policy', 'default-src 'none'; frame-ancestors 'none''
'date', 'Fri, 17 Oct 2025 09:29:39 GMT'
'server', 'envoy'

After fixing the route matching, we are correctly catching and redirecting in staging, however:

for host in wikimedia.org www.wikidata.org test.wikidata.org commons.wikimedia.org test-commons.wikimedia.org en.wikipedia.org en.wiktionary.org en.wikivoyage.org wikisource.org; do echo $host; curl -k -H "Host: ${host}" https://staging.svc.eqiad.wmnet:4113/wikimedia.org/v1/?spec -s -w "%{http_code}\n" -o /dev/null; done
wikimedia.org
301
www.wikidata.org
200
test.wikidata.org
200
commons.wikimedia.org
200
test-commons.wikimedia.org
200
en.wikipedia.org
200
en.wiktionary.org
200
en.wikivoyage.org
200
wikisource.org
200

It works for all but wikimedia.org, which if I remember correctly is a bit of a "special" wiki, with multiple redirects etc.

I'll deploy to the production rest-gateway since nothing points these paths there at the moment, but this will need to get investigated.

aaron added a comment.Oct 23 2025, 10:29 PM

So...it looks like mediawiki-config needs some tweaks under docroot. wikimedia.org redirects to www.wikimedia.org which has the wwwportal docroot, not the wikimedia one. I think I'll just make an api/restbase_specs dir under wwwportal and move rest_v1-wikimedia.json there.

gerritbot added a comment.Oct 23 2025, 10:29 PM

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

[operations/mediawiki-config@master] Move rest_v1-wikimedia.json under the wwwportal directory

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

gerritbot added a comment.Oct 23 2025, 10:34 PM

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

[operations/deployment-charts@master] restgateway: update spec-json-wikimedia to use www prefix

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

gerritbot added a comment.Oct 27 2025, 8:48 PM

Change #1198405 merged by jenkins-bot:

[operations/mediawiki-config@master] Move rest_v1-wikimedia.json under the wwwportal directory

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

Stashbot added a comment.Oct 27 2025, 8:48 PM

Mentioned in SAL (#wikimedia-operations) [2025-10-27T20:48:45Z] <aaron@deploy2002> Started scap sync-world: Backport for [[gerrit:1198405|Move rest_v1-wikimedia.json under the wwwportal directory (T396805)]]

Stashbot added a comment.Oct 27 2025, 8:52 PM

Mentioned in SAL (#wikimedia-operations) [2025-10-27T20:52:32Z] <aaron@deploy2002> aaron: Backport for [[gerrit:1198405|Move rest_v1-wikimedia.json under the wwwportal directory (T396805)]] synced to the testservers (see https://wikitech.wikimedia.org/wiki/Mwdebug). Changes can now be verified there.

Stashbot added a comment.Oct 27 2025, 9:01 PM

Mentioned in SAL (#wikimedia-operations) [2025-10-27T21:01:08Z] <aaron@deploy2002> Finished scap sync-world: Backport for [[gerrit:1198405|Move rest_v1-wikimedia.json under the wwwportal directory (T396805)]] (duration: 12m 22s)

gerritbot added a comment.Oct 29 2025, 4:22 PM

Change #1177515 merged by Clément Goubert:

[operations/puppet@production] Route "/api/rest_v1/?spec" requests to the rest gateway

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

Clement_Goubert added a comment.Oct 29 2025, 5:10 PM

I had to revert the ATS patch, as it is the gateway-check.lua script is not able to route based on GET uri args, only the path.
I'll try to think of an elegant-ish way to handle this tomorrow.

gerritbot added a comment.Oct 30 2025, 12:38 AM

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

[operations/puppet@production] Route "/api/rest_v1/" requests with "?spec" query to the rest gateway

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

gerritbot added a comment.Nov 1 2025, 4:14 AM

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

[operations/mediawiki-config@master] Add a wgRestSandboxSpecs entry for wikimedia.org (math) specs

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

gerritbot added a comment.Nov 3 2025, 9:29 AM

Change #1199886 merged by Clément Goubert:

[operations/puppet@production] Route "/api/rest_v1/" requests with "?spec" query to the rest gateway

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

gerritbot added a comment.Nov 3 2025, 9:07 PM

Change #1190742 merged by jenkins-bot:

[operations/mediawiki-config@master] Set wgRestSandboxSpecs['wmf-restbase'] on testwiki to use the static specs

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

Stashbot added a comment.Nov 3 2025, 9:08 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-03T21:08:09Z] <aaron@deploy2002> Started scap sync-world: Backport for [[gerrit:1190742|Set wgRestSandboxSpecs['wmf-restbase'] on testwiki to use the static specs (T396805)]]

Stashbot added a comment.Nov 3 2025, 9:10 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-03T21:10:19Z] <aaron@deploy2002> aaron: Backport for [[gerrit:1190742|Set wgRestSandboxSpecs['wmf-restbase'] on testwiki to use the static specs (T396805)]] synced to the testservers (see https://wikitech.wikimedia.org/wiki/Mwdebug). Changes can now be verified there.

Stashbot added a comment.Nov 3 2025, 9:15 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-03T21:15:25Z] <aaron@deploy2002> Finished scap sync-world: Backport for [[gerrit:1190742|Set wgRestSandboxSpecs['wmf-restbase'] on testwiki to use the static specs (T396805)]] (duration: 07m 16s)

gerritbot added a comment.Nov 3 2025, 9:17 PM

Change #1190743 merged by jenkins-bot:

[operations/mediawiki-config@master] Set wgRestSandboxSpecs['wmf-restbase'] to use the static specs everywhere

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

Stashbot added a comment.Nov 3 2025, 9:18 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-03T21:18:03Z] <aaron@deploy2002> Started scap sync-world: Backport for [[gerrit:1190743|Set wgRestSandboxSpecs['wmf-restbase'] to use the static specs everywhere (T396805)]]

Stashbot added a comment.Nov 3 2025, 9:20 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-03T21:20:16Z] <aaron@deploy2002> aaron: Backport for [[gerrit:1190743|Set wgRestSandboxSpecs['wmf-restbase'] to use the static specs everywhere (T396805)]] synced to the testservers (see https://wikitech.wikimedia.org/wiki/Mwdebug). Changes can now be verified there.

Stashbot added a comment.Nov 3 2025, 9:25 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-03T21:25:35Z] <aaron@deploy2002> Finished scap sync-world: Backport for [[gerrit:1190743|Set wgRestSandboxSpecs['wmf-restbase'] to use the static specs everywhere (T396805)]] (duration: 07m 31s)

gerritbot added a comment.Nov 4 2025, 10:36 AM

Change #1198406 merged by jenkins-bot:

[operations/deployment-charts@master] restgateway: update spec-json-wikimedia to use www prefix

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

gerritbot added a comment.Nov 4 2025, 10:45 PM

Change #1200441 merged by jenkins-bot:

[operations/mediawiki-config@master] Add a wgRestSandboxSpecs entry for wikimedia.org (math) specs

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

Stashbot added a comment.Nov 4 2025, 10:45 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-04T22:45:34Z] <aaron@deploy2002> Started scap sync-world: Backport for [[gerrit:1200441|Add a wgRestSandboxSpecs entry for wikimedia.org (math) specs (T396805)]]

Stashbot added a comment.Nov 4 2025, 10:47 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-04T22:47:54Z] <aaron@deploy2002> aaron: Backport for [[gerrit:1200441|Add a wgRestSandboxSpecs entry for wikimedia.org (math) specs (T396805)]] synced to the testservers (see https://wikitech.wikimedia.org/wiki/Mwdebug). Changes can now be verified there.

Stashbot added a comment.Nov 4 2025, 10:53 PM

Mentioned in SAL (#wikimedia-operations) [2025-11-04T22:53:22Z] <aaron@deploy2002> Finished scap sync-world: Backport for [[gerrit:1200441|Add a wgRestSandboxSpecs entry for wikimedia.org (math) specs (T396805)]] (duration: 07m 48s)

Maintenance_bot removed a project: Patch-For-Review.Nov 4 2025, 11:31 PM
aaron closed this task as Resolved.Nov 5 2025, 12:15 AM
aaron triaged this task as Medium priority.
aaron set the point value for this task to 5.
aaron updated the task description. (Show Details)
aaron edited projects, added MW-Interfaces-Team (MWI-Sprint-22 (2025-11-04 to 2025-11-18)); removed MW-Interfaces-Team.Nov 5 2025, 12:20 AM
gerritbot added a comment.Nov 5 2025, 11:06 PM

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

[operations/deployment-charts@master] restgateway: make spec-json-wikimedia catch non-www domain too

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

gerritbot added a project: Patch-For-Review.Nov 5 2025, 11:06 PM
gerritbot added a comment.Nov 7 2025, 12:04 AM

Change #1202323 abandoned by Aaron Schulz:

[operations/deployment-charts@master] restgateway: make spec-json-wikimedia catch non-www domain too

Reason:

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

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

Maintenance_bot removed a project: Patch-For-Review.Nov 7 2025, 12:30 AM
aaron moved this task from Committed to Demo Ready! on the MW-Interfaces-Team (MWI-Sprint-22 (2025-11-04 to 2025-11-18)) board.Dec 1 2025, 8:46 PM
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 · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits