Positional vs named parameters

[DaveCTurner]

Today we leniently accept named parameters in place of positional ones in some REST APIs. For instance:

elasticsearch/server/src/main/java/org/elasticsearch/rest/action/admin/cluster/RestClusterStatsAction.java

Lines 35 to 36 in 99f88f1

	controller.registerHandler(RestRequest.Method.GET, "/_cluster/stats", this);
	controller.registerHandler(RestRequest.Method.GET, "/_cluster/stats/nodes/{nodeId}", this);

The right way™ to get the cluster stats restricted to a subset of the nodes is

GET /_cluster/stats/nodes/node1,node2,...

However, the following also works:

GET /_cluster/stats?nodeId=node1,node2,...

I think in this case we should not accept nodeId as a named parameter.

Relates #36784

[elasticmachine]

Pinging @elastic/es-core-infra

[jaymode]

The core/infra team discussed this today. One item that we also looked at was the behavior when both a positional and named parameter are used at the same time. In that case, the positional parameter is used and the named parameter is ignored and is not considered an unused/unconsumed parameter. The team also discussed whether we needed to address this and the outcome is that we should address it because we're allowing a way of operating that is untested and could hurt users by unknowingly making changes that break their use of a positional parameter as a named parameter.

The plan is to deprecate this behavior and add a compatibility layer to limit the impact to clients.

[pgomulka]

while I also agree that warning users about this is useful but there is no infrastructure to distinguish between a named and positional parameter at the moment.
We should refactor our request/path parsing logic so that we can enrich parameters with information where are they coming from.

[DaveCTurner]

++ I imagine we could have two maps of parameters, introduce more specific queryParam() and pathParam() APIs and then deprecate and progressively move away from todays lenient param() APIs.

[elasticsearchmachine]

Pinging @elastic/es-core-infra (Team:Core/Infra)