cluster/allocation/explain Query Parameters

[joshua-adams-1]

---

Change Details

Extends the documentation for the cluster/allocation/explain API after query parameter support was added in elastic/elasticsearch#129342

• The query parameters are defined, and the descriptions are updated based on comments from Add Cluster/Allocation/Explain Query Param Example #4849
• A second request example was provided, highlighting how to pass all parameters in the URL string rather than the request body

---

Release

To be merged after elastic/elasticsearch#129342

---

Github Issue - elastic/elasticsearch#127028
Jira Ticket - ES-11865

[github-actions]

Following you can find the validation changes against the target branch for the API.

API	Status	Request	Response
cluster.allocation_explain	🔴	8/17 → 10/17	17/17

You can validate this API yourself by using the make validate target.

[pquentin]

Validation currently fails because you have YAML tests where primary can be a string. Is it really needed?

https://github.com/elastic/elasticsearch/blob/f135998b118d4e58922300cf942506ae25cd7ab1/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cluster.allocation_explain/10_basic.yml#L297-L299

[joshua-adams-1]

According to the ElasticSearch API, it is documented that we facilitate strings to be passed for boolean values. I was adding YAML Rest Tests to ensure that if a user is to do so, we correctly parse this and proceed as expected.

A separate question, why is validation here subjected to whether or not a YAML rest test exists / does not exist? What changes if I was to delete the test?

[pquentin]

Looking more closely, we have YAML tests allowing different types in multiple places. Here is the full list of changes needed to make the validation pass. This won't give a good developer experience. I don't recommend applying this diff unless there's a good reason.

diff --git a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts
index 50cda8f21..5bffd3ce4 100644
--- a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts
+++ b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts
@@ -48,15 +48,15 @@ export interface Request extends RequestBase {
     /**
      * The name of the index that you would like an explanation for.
      */
-    index?: IndexName
+    index?: IndexName | integer
     /**
      * An identifier for the shard that you would like an explanation for.
      */
-    shard?: integer
+    shard?: integer | string
     /**
      * If true, returns an explanation for the primary shard for the specified shard ID.
      */
-    primary?: boolean
+    primary?: boolean | string
     /**
      * Explain a shard only if it is currently located on the specified node name or node ID.
      */
@@ -65,12 +65,12 @@ export interface Request extends RequestBase {
      * If true, returns information about disk usage and shard sizes.
      * @server_default false
      */
-    include_disk_info?: boolean
+    include_disk_info?: boolean | string
     /**
      * If true, returns YES decisions in explanation.
      * @server_default false
      */
-    include_yes_decisions?: boolean
+    include_yes_decisions?: boolean | string
     /**
      * Period to wait for a connection to the master node.
      * @server_default 30s
@@ -85,11 +85,11 @@ export interface Request extends RequestBase {
     /**
      * An identifier for the shard that you would like an explanation for.
      */
-    shard?: integer
+    shard?: integer | string
     /**
      * If true, returns an explanation for the primary shard for the specified shard ID.
      */
-    primary?: boolean
+    primary?: boolean | string
     /**
      * Explain a shard only if it is currently located on the specified node name or node ID.
      */

[pquentin]

Thanks! LGTM. Validation fails but this will be fixed by removing some YAML tests from Elasticsearch.