Page MenuHomePhabricator
Create Task
Maniphest T427806

Allow users to request a generated OpenAPI spec in any language
Open, MediumPublic5 Estimated Story Points
Actions

Description

Description

Last year, we introduced the ability to translate and localize OpenAPI specs generated within the MediaWiki framework. Today, the spec language follows the default language for the wiki it is being requested on. However, we would also like to offer the ability to request the spec in any language. The ability to request any language will support "Project Frodo", where specs are being pulled and displayed outside of the context of MediaWiki. Additionally, there are some users who may prefer using a spec in cases where their preferred language does not match the default wiki value.

Conditions of Acceptance

  • Allow a language to be specified when requesting a generated spec using the /specs endpoint
    • Language is specified using 2-character ISO code (with a few exceptions)
    • Some languages may also have dialect options specified beyond the ISO version -- for example, zh-hans vs zh-hant.
  • When a language is specified, the spec is generated in the requested language (if translation is available). If no language is specified, continue using the default language for the requested wiki. This includes cases where an invalid language code is provided; instead of throwing an error, simply fallback to the default language.

Implementation details

Two options exist for allowing a language to be specified: 1) Using the standard Accept-Lanaguage header, 2) A query parameter, or 3) Adding a path parameter.

For now, the product recommendation is to add a query parameter for this specification. This is because query parameters are more explicit and clear on the request, more cacheable, and easier for most users to deal with than headers. However, if a strong case is made for one of the other approaches, we can discuss it as a team.

The query parameter pattern would look something like:
https://test.wikipedia.org/w/rest.php/specs/v0/module/attribution/v0-beta?lang=es

A few ideas for the query parameter name itself:

  • [RECOMMENDED] ?lang=en --> Seems to be fairly commonly used across REST implementations
  • ?uselang=en --> Consistent with the Action API
  • ?language=en --> Potential clarity over an abbreviated version; out in the wild, this frequently has both words spelled out (eg: ?language=English)
NOTE: The scope of this work does not include adding a language picker to the REST Sandbox. The REST Sandbox will continue to model the current behavior of using the default wiki language; the ability to request and view the spec in any language will be native to the Unified Developer Front-door.

Related Objects
Search...

Event Timeline

HCoplin-WMF created this task.Jun 1 2026, 1:51 PM
HCoplin-WMF renamed this task from Allow users to request a generated spec in any language to Allow users to request a generated OpenAPI spec in any language.
HCoplin-WMF added a project: MW-Interfaces-Team.
HCoplin-WMF moved this task from Incoming (Needs Triage) to To Refine on the MW-Interfaces-Team board.
BPirkle subscribed.Jun 4 2026, 2:04 PM

Two options exist for allowing a language to be specified: 1) Using the standard Accept-Lanaguage header, 2) A query parameter, or 3) Adding a path parameter.

There are only two hard problems in computer science...

I think you probably meant to delete #3, but if not, I'll add that we intentionally don't support optional path parameters in the MW REST API. Adding a path parameter to an existing endpoint would be a breaking change. I'd therefore favor #1 or #2. Probably #2 as "uselang" for consistency with the Action API, even though I'm not a huge fan of that naming, although technically there's no reason we couldn't have multiple path parameters (both "lang" and "uselang") that do exactly the same thing. That might be worse and not better, just want to add that it would be possible.

BPirkle added a comment.Jun 4 2026, 2:44 PM

Discussion from estimation:

  • we don't currently have the concept in the MW REST API of a "universal" query parameter that applies to all endpoints. If we use a query parameter, we could consider adding that capability
  • endpoints could still potentially override the behavior if desired. Maybe?
  • language determination (via creation of text formatters) currently occurs very early in the REST API execution process, while per-handler query parameter validation occurs much later. If we use a query parameter, we'll need to resolve that
  • All the above say "query parameter" but using a header doesn't necessarily make any of this easier. The same considerations still apply.
  • Are there caching considerations that would guide us towards either a query parameter or a header?
BPirkle set the point value for this task to 5.Jun 4 2026, 2:45 PM
HCoplin-WMF moved this task from To Refine to Ready, Sized, & Prioritized on the MW-Interfaces-Team board.Tue, Jun 16, 11:12 AM
HCoplin-WMF triaged this task as Medium priority.Tue, Jun 16, 6:48 PM
HCoplin-WMF added a project: Wikimedia-Developer-Portal.
HCoplin-WMF updated the task description. (Show Details)
HCoplin-WMF added a comment.Tue, Jun 16, 7:38 PM

Are there caching considerations that would guide us towards either a query parameter or a header?

Based on what I've read, it seems that caching is better with a query parameter over a header. I'm not sure if that changes at all based on where the execution is happening though, to your other point.

we don't currently have the concept in the MW REST API of a "universal" query parameter that applies to all endpoints. If we use a query parameter, we could consider adding that capability

Whoever picks up this ticket should make that assessment, including whether or not we need another ticket to cover that work.

HCoplin-WMF moved this task from Ready, Sized, & Prioritized to MediaWiki-Interfaces-Sprints on the MW-Interfaces-Team board.Tue, Jun 30, 3:24 PM
HCoplin-WMF edited projects, added: MW-Interfaces-Team (MediaWiki-Interfaces-Sprints); removed: MW-Interfaces-Team.
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