Allocation explain should accept query-string parameters

[DaveCTurner]

Today allocation explain takes its parameters in the request body:

GET _cluster/allocation/explain
{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}

Leaving aside the question of the validity of GET-with-body (you can use POST here) it's also just kinda awkward to pass in a flat map of 4 somewhat-optional parameters in the body. We could just as well make the API accept the same parameters in the query-part of the URI¹:

GET _cluster/allocation/explain?index=my-index-000001&shard=0&primary=false&current_node=my-node

Note that we probably shouldn't accept a mix of these two styles: if there are any parameters, they must all be in the body or all in the query string. We might even want to deprecate the use of the body for these arguments and remove it in the next major?

Footnotes

1. Technically ok you can already do this using the source and source_content_type params:

   GET _cluster/allocation/explain?source_content_type=application/json&source=%7B%22index%22%3A%22my-index-000001%22%2C%22shard%22%3A0%2C%22primary%22%3Afalse%2C%22current_node%22%3A%22my-node%22%7D
   

   But eh that's not all that nice is it? ↩

[elasticsearchmachine]

Pinging @elastic/es-distributed-coordination (Team:Distributed Coordination)

[joshua-adams-1]

If we deprecate the existing behaviour of passing the parameters via the body and replace it with parameters attached in the URL then this is a breaking change to all existing API users. How can we verify the impact of this change? Is this URL available externally to Elastic (ie to external customers?) If so, what is the process of deprecating an API and replacing it with another version?

[DaveCTurner]

Yes this is an externally-visible API. All we can do for now is log a warning using a org.elasticsearch.common.logging.DeprecationLogger to tell users that they need to change their ways before upgrading to the next major version. I'd suggest not doing that in the first PR, instead leaving it to a followup since it needs some extra approval from the product folks.

[joshua-adams-1]

#129342 - This PR extends the ElasticSearch API to support parameters via both the request body and via query parameters

elastic/elasticsearch-specification#4849 - This PR extends the ElasticSearch documentation to reflect these API changes