I think this is done. If T362480: Introduces the notion of modules into the REST API framework continues the direction it is currently trending and is merged, then it changes some things with the MW REST API swagger spec that we'll want to address. But that would be more properly done under a new task.

Move the logic into a REST endpoint, and turn opensearch_desc.php into a redirect
Deprecate and eventually remove opensearch_desc.php

As @Tgr points out, the term "post" is confusing because it could be taken to mean either the HTTP POST method or $_POST.

1. Risky Patch! 🚂🔥

Patches merged, this is done. Thanks for thoughts and review.

I'm unsure whether to comment on the patch or here, as there is discussion in both places and it is a different set of people participating in each. I chose here because, from what I've seen, Phab tends to be more useful as a decision record, and also tends to be used by both engineers and non-engineers (EMs, PMs, etc.).

I've marked the core change as ready for review.

Looking through the potentially affected code, to see what would need to be changed if we go with the approach from my previous comment.

Daniel and I discussed this a bit more in Slack, and agreed to modify the plan somewhat. We will still be disallowing optional path parameters in routes. But we will be allowing them in handlers (more specifically, in GetParamSettings()).

In T359652#9669843, @daniel wrote:

I think it's useful to have suport for optional parameters in the parameter validator, so we can register the same handler for multiple routes, some of which may be missing some parameters.

The above patch just adds a few more test cases for PathMatcher. It does not change any existing PathMatcher behaviors.

In T359652#9674146, @Krinkle wrote:

• We have no known uses of, or use cases for, optional path components — other than the current Reading Lists API migration.

In T359652#9669843, @daniel wrote:

I think it's useful to have suport for optional parameters in the parameter validator, so we can register the same handler for multiple routes, some of which may be missing some parameters.

There might be a sixth option. If /myextension/foo/ and /myextension/foo/{id} (where ID can be optional) are considered conflicting routes today, does that mean there is also the option of implementing what you're looking for, by registering the latter and having the route handler respond with what you want from a conditional !id branch?

Hearing no objections, I'm planning to work on patches for disallowing non-required path parameters in the REST API. If anyone thinks that's a bad idea, please say so.

To elaborate a bit on the OpenAPI/Swagger issue this section of the swagger.io params documentation page reinforces that path parameters cannot be non-required. Specifically, this text: "path parameters must have required: true, because they are always required."

Tagging MW Engineering for visibility. Not promising this will be picked up, but we'll at least triage it.

REST API endpoints were created for (the duplicate of) this task. They were then determined to be unnecessary and will be removed as unused under https://gerrit.wikimedia.org/r/c/mediawiki/core/+/779917

REST API endpoints were created for this task. They were then determined to be unnecessary and will be removed as unused under https://gerrit.wikimedia.org/r/c/mediawiki/core/+/779917

Summary of related Slack discussion that occurred before this task was created. @daniel and @pmiazga , please correct anything that I misrepresented from your Slack comments.

Triaging this as Low priority, mostly because it has been around quite some time and it seems people are working around this for the moment. Feel to raise the priority if this is a blocker for anything you're doing.

Unable to reproduce at the moment. Which doesn't mean this isn't an issue, it just means it is challenging to diagnose.

Initial implementation of new handlers have been merged and is available on production. Nothing is routing to them, so there is no change to callers at this time. WMF Mobile apps are still hitting the RESTBase endpoints, with no changes. This will be the case until we proactively reroute calls to the new endpoints via the API Gateway. We do not plan to do this until callers have had the opportunity to review changes, and any necessary adjustments are made.

Added the following parameters that were previously exposed by the underlying Action API endpoint, but not by RESTBase:

Added the following parameter that was previously exposed by the underlying Action API endpoint, but not by RESTBase:

Added the following parameters that were previously exposed by the underlying Action API endpoint, but not by RESTBase:

Open API spec for all new REST endpoints is available here: https://meta.wikimedia.beta.wmflabs.org/w/rest.php/

The current JsonBodyValidator checks for extraneous parameters in the body. It would be good to not lose that ability.

There has been some discussion of continuation values (as they apply to the GET /lists/ and GET /lists/entries endpoints) in synchronous meetings. There's some related information in T182706: Make sure apps can continue /changes/since where they left off (which I do not pretend that I completely understand as of this writing). But as it applies to Reading Lists, here is what I think is going on (someone please correct me if they see that I am wrong):