More details on that error message in comments on T416532: REST: create specs.v1 module

After discussion with Product Management, we will remove content.v1 and coreDevelopmerntRoutes.json from core.

I see patches by C. Scott, so I'm assuming CTT is handling this. Please adjust if I'm incorrect.

@HCoplin-WMF , as part of this task I'd like to:

• turn off the content.v1 module, which is currently only available on test and beta, and which receives essentially no traffic. The module file can stay in the codebase. Having it present doesn't cause any annoyance, but having it active does.
• remove coreDevelopmentRoutes.json, which is a placeholder that is no longer relevant, and which is also available only on test and beta. Having this in the codebase at all causes annoyance, and its purpose has been replaced by the module system and the beta audience designation.

Closing. We're dealing with tests under other tasks.

Not sure where this task currently stands. Adding MWI team for evaluation and triage, removing older tags.

Older task, no longer relevant.

From the task description:

Discussion notes/questions:

• bots tend to use owner-only, which grants a permanent access token. Other flows are possible.
• does refresh url need to be in the spec?
• how do OAuth scopes relates to MW grants? (Roughly, we think, "grants" is a MediaWiki authorization term that maps to OAuth 2 scopes)
• OAuth client/consumer creation form: https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
• API Portal had a simplified version of that form. Not sure yet of its future not that API Portal is being turned off - project "Frodo" may feature a replacement.
• our OAuth extension supports OAuth 1.0a. Is this task specifically for OAuth 2 only, or do we need to cover both?
• could we just support OAuth 2 in OpenAPI? We're at least soft-discouraging OAuth 1.0a, and the simplified form on API portal never supported 1.0a.
• at the moment, OAuth consumer/client creation is a human-involved process that requires someone to actually click a button to approve your request
• our terminology is inconsistent. Our OAuth extension first supported only 1.0a, and later we added 2.0, but we never got the wording all correct, so 1.0a-specific terms appear on 2.0 pages, etc. This affects both the user-facing forms as well as the code.
• do we care about JWTs at this level? Does it matter what form tokens take? Does anything about rate limiting appear at all here, or is that irrelevant?

We ended up removing opt-in as a separate functionality set (aka "mode"). Instead, that mode will be represented by the published mode, with an accompanying group value.

Filed T428375: REST: External Modules with implementation plan.

As far as I can tell, the RestSandbox can load a server-side file, or does a client-side GET for url-defined specs, so the end-state would be to have something like https://api.wikimedia.org/service/lw/openapi.yaml or similar in wgRestSandboxSpecs

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?

Some decisions remain about exactly how the default is specified and what it affects. For instance, does it also affect /discovery? Are there implications for the upcoming Unified Front Door (aka Frodo) project?

Also per discussion, we will likely elevate the "routes not in modules" to the top, and sort alphabetically after that. Need to confirm this with Product Management.

After discussion, T422211: Allow specifying default REST module in the Special:RestSandbox is not a prerequisite. We could implement a basic default sorting, and then add in the ability to set a per-wiki specific default later.

Decided on a 2 after sync discussion

Decided on a 3 after sync discussion

Decided on a 5 after sync discussion

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.

Async estimation results:

Async estimate results:

Async estimate results:
3 points: 3 votes: @Moriel (she/her), @aschulz, @aghirelli
2 points: 3 votes: @BPirkle, @mgoncalves, @Hua Szu Yang

In T427815#11978143, @Ottomata wrote:

unclear whether Data Engineering is planning to do this work, or is requesting MediaWiki Interfaces to do it.

Hoping for a collaboration. DPE will drive prioritization through OKRs, so stay tuned!

In T427817#11977933, @Ottomata wrote:

I created this task as a way to start having that convo. I think it will have to be a cross team effort. I expect this work to be prioritized (or not) via the usual OKR process.

Estimated synchronously during sprint planning

Estimated synchronously during sprint planning.

I'm unclear whether Data Engineering is planning to do this work, or is requesting MediaWiki Interfaces to do it. I see the task in Backlog on a DPE board, so I'm assuming the former and putting this in MWI's Radar column. If that's incorrect, please adjust.

I'm unclear whether Data Engineering is planning to do this work, or is requesting MediaWiki Interfaces to do it. I see the task in Backlog on a DPE board, so I'm assuming the former and putting this in MWI's Radar column. If that's incorrect, please adjust.

Not that it hurts anything, as these strings are technically arbitrary, but this does lead to some slightly odd operationId names, such as:

• getGetRevisionSource
• getGetRevisionHtml
• getGetRevisionInformationWithHtml
• getGetRevisionLintErrors
• postCreatePage (which makes sense if you know it's an HTML method, but if you don't it sounds a little like "after a page is created"

I'm skeptical about using $wgVersion for this.

The sitemap endpoints mentioned in the description are a little uncommon in that they return application/xml rather than application/json. We always expected that handlers that do uncommon things would have to override things in uncommon ways (which still seems reasonable to me). I don't think that changes much in this task - we still do want a way to add examples in the general case - but it is worth pointing out that sitemap is a little unusual and therefore we should be careful when considering it as part of the general pattern.

The rate limiting classes seem like a great way to think about the traffic/audience/caller types. I'm not convinced that using the rate limiting service to do the actual blocking is the right choice, but I'll let folks closer to that work weigh in.

I'm leaning towards the 301 redirect. It seems cleaner in a variety of ways.

Patch merged, further improvements, if we choose to make any, can be done under a separate task.