See also T392278: Create a MW REST API endpoint for fetching CSRF tokens.

See also T409251: Special:RestSandbox should auto-fill tokens, or have a button to auto-fill tokens

The patch I just uploaded allows for links that automatically scroll to and expand a particular endpoint in the REST Sandbox. I attached it to this task in case it is useful for links from the on-wiki documentation to the REST Sandbox.

Summary of the conversation that Atieno and I had yesterday:

• we have two primary goals for the initial phase of the Handler refactoring:
  • make it more convenient to generate specs outside the context of a rest.php request (for example, from a maintenance script)
  • make it more obvious to developers what things they need to override to properly generate a spec for their endpoint(s)
• the current (as of this writing) patch introducing SpecGenerator may have promise, but doesn't yet meet those goals
  • it does move some code out of Handler
  • it doesn't make generating specs from a maintenance script more convenient
  • it doesn't make it more clear what developers need to override for spec generation
• suggestions that I made for moving the patch forward
  • move the functions in Handler that developers must currently override for spec generation into SpecGenerator
    • developers would not create classes derived from SpecGenerator for their endpoint(s)
    • developers would also create a derived Handler class, and instantiate their derived SpecGenerator class from there
    • this derived SpecGenerator instance would be injected or otherwise passed to the base Handler class
    • we'd need a transition plan for the (many) people currently overriding the Handler functions
    • this helps with both goals, but also introduces a parallel class hierarchy that may be equally confusing
  • create static constants for parameter/schema definitions (likely including schema file location)
    • these constants would be injected or otherwise passed to SpecGenerator
    • developers would now create constants instead of overriding functions (which is hopefully simpler)
    • SpecGenerator could be used from a maintenance script without a Handler instance, based only on the derived Handler classname
    • this approach may still be confusing
    • this approach doesn't help in cases where logic must be performed in the param/schema definitions (CSRF token inclusion, RESTbase compat, etc.)
  • create static functions in Handler that derived Handler instances would override
    • this is basically the same as the above, except no injection or passing of constants required
    • allows for logic in the param.schema definitions
    • is this straightforward enough, or still confusing?
• Atieno to explore the options and post at least one and probably multiple WIP patches for feedback

I'm unclear on the impact of this bug. If it is more impactful than a "Medium" priority, please bump that up.

Older issue, not sure if it is still relevant. Looks more like Content Transform than MediaWiki Interfaces, so tagging them and untagging us. Please retag if I'm wrong about that.

I believe that MWI's role here is feedback, and Tech Docs is doing the actual work, so moving this to our Radar column. If I'm wrong, we can move accordingly.

Took a quick look at this, and my first impression is that it will be a nontrivial amount of work. Ideally, we'd finish the current Handler refactoring work before starting the work to make linting pass.

SiteMatrix is unassigned on the Maintainers page. I'll put this on our Bugs & Chores list, but that should not discourage anyone else who might want to look at this. I can't promise when it might get attention from us.

I mentioned this in the patch, but if you follow the pattern you're currently pursuing, you're going to have to figure out how to let derived classes override functionality that now lives in SpecGenerator. There are a lot of ways to do this, so pick whatever you think is best.

Adding to sprint. Merged patch has added the missing strings, but as Amir points out the wording could be improved to help with translation.

Doesn't look like this is for MediaWiki Interfaces. And it has a match merged. Please retag us if we're needed.

In T391712#11187232, @HCoplin-WMF wrote:

Just so we don't lose track of it with https://phabricator.wikimedia.org/T392608 being resolved -- we do need to figure out what to do in terms of hiding and/or deprecating the endpoints with the trailing slash. I would be in favor of hiding them from the sandbox and announcing an official deprecation. I'll add subtasks here for both of those efforts.

The REST Sandbox is now available on all wikis, with the following initial set of modules:

• flat routes (routes not in modules) in coreRoutes.json
• flat routes (routes not in modules) in various extensions
• Specs module

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.

In T405373#11229022, @Atieno wrote:

Proposal

Per discussion outside of Phabricator, we will initially enable the following specs on all wikis:

• "MediaWiki REST API (routes not in modules)" aka "flat routes" aka "routes in coreRoutes.json"
  • available on all wikis
  • spec url: /w/rest.php/specs/v0/module/-
• Specs module
  • will be made available on all wikis as part of this change (via wgRestAPIAdditionalRouteFiles)
  • spec url: /w/rest.php/specs/v0/module/specs/v0
  • provides an example of exposing a module via the REST Sandbox
  • the urls provided by this module will be visible as part of exposing the coreRoutes.json endpoints, and it is already visible on our initial set of wikis. So it seems a little silly to not put this in the sandbox everywhere too.
• "Wikimedia RESTbase APIs" aka the specs created under T396805: Define static OpenAPI specs per API family for RESTbase endpoints
  • rerouting is complete for these specs
  • spec url: /api/rest_v1/?spec

This change to mark these endpoints as deprecated in the OpenAPI spec is riding this week's train.

Basic deprecation support (flag in OpenAPI spec, header on endpoint execution) is merged and riding this week's train.

After separate conversations with @daniel and @HCoplin-WMF, here is the a proposal for what will be done in the initial patch, plus a plan for how this might be extended for possible future additions.

In T405373#11229022, @Atieno wrote:

This Proposal is Still a WIP:

Thank you for the thoughts, @daniel ! Continuing the conversation below...

Removing inactive assignee

Lots to do on the REST Sandbox, but not under this task - there are already separate tasks for that work. Closing this task as resolved.

Unclear whether this is actually an API issue, or an issue with underlying code belonging to another team. Moving to our Bugs & Chores column for investigation, but we have no set time frame for that. If anyone else is inclined to investigate first, feel free.

Unclear what component is actually the cause here, but moving to our Bugs & Chores column for investigation. I am unsure when we'll get to this, so this should not deter others from investigating if they are inclined to do so.

Resolving this older task because a baseline of documentation has been completed. There are (many) documentation improvements remaining to be made, but they are covered by other tasks.

I'm seeing discussion of this in Slack, so moving it into the current sprint.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

Closing old task. If we were prioritize slot support, we'd need to reconsider it to account for changes since then. And as the comment above says, the task description was never complete in the first place.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

This work was handled under separate tasks and is no longer relevant.

Per discussion in standup meeting, here are my chief complaints with Handler as it currently exists:

On this bullet point:

In T405038#11207030, @HCoplin-WMF wrote:

A suggestion for the actual text to add to the description might be:

Normal endpoint description.

WARNING: This endpoint is deprecated. It will be removed on or around {Month} DD, YYYY.

After discussion, we decided on the following:

tl;dr: support adding something like the following in endpoint specs (both module definition files and the old flat format):
deprecated: true
x-deprecation:date: 1688169599

I'm a little late to the party here, and trying to catch up. Bear with me as I repeat some things that have already been said, consolidating them from multiple sources.

In T405038#11195696, @HCoplin-WMF wrote:

Minor callout about the RESTBase API -- it seems like they only designate the stability policy within the endpoint documentation descriptions. Is that accurate? I don't see any examples of actually using the deprecated: true designation in the spec; the only endpoint I see that is currently marked as deprecated is POST Reading lists, but it is only called out in the endpoint description there.