rest-api-spec: use list type in parts when appropriate (elastic#137568) (elastic#138154)

pquentin · web-flow · commit 49302cf621b5 · 2025-11-17T11:28:24.000+01:00
* rest-api-spec: use list type in parts when appropriate

Many APIs accept comma-separated values in the path, which is encoded by using
the `list` type.

* Mention comma-separated list in descriptions
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.delete_component_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.delete_component_template.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "The name of the template"
+              "type": "list",
+              "description": "Comma-separated list or wildcard expression of component template names used to limit the request."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.exists_component_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.exists_component_template.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "The name of the template"
+              "type": "list",
+              "description": "Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/eql.search.json b/rest-api-spec/src/main/resources/rest-api-spec/api/eql.search.json
@@ -24,8 +24,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "The name of the index to scope the operation"
+              "type": "list",
+              "description": "Comma-separated list of index names to scope the operation"
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/health_report.json b/rest-api-spec/src/main/resources/rest-api-spec/api/health_report.json
@@ -26,8 +26,8 @@
           ],
           "parts": {
             "feature": {
-              "type": "string",
-              "description": "A feature of the cluster, as returned by the top-level health API"
+              "type": "list",
+              "description": "Comma-separated list of cluster features, as returned by the top-level health report API."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.cancel_migrate_reindex.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.cancel_migrate_reindex.json
@@ -23,8 +23,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "The index or data stream name"
+              "type": "list",
+              "description": "Comma-separated list of index or data stream names"
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete_index_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete_index_template.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "The name of the template"
+              "type": "list",
+              "description": "Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.disk_usage.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.disk_usage.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "Comma-separated list of indices or data streams to analyze the disk usage"
+              "type": "list",
+              "description": "Comma-separated list of data streams, indices, and aliases used to limit the request. It\u2019s recommended to execute this API with a single index (or the latest backing index of a data stream) as the API consumes resources significantly."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.explain_data_lifecycle.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.explain_data_lifecycle.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "The name of the index to explain"
+              "type": "list",
+              "description": "Comma-separated list of index names to explain"
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.field_usage_stats.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.field_usage_stats.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices"
+              "type": "list",
+              "description": "Comma-separated list or wildcard expression of index names used to limit the request."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_data_stream_mappings.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_data_stream_mappings.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "Comma-separated list of data streams or data stream patterns"
+              "type": "list",
+              "description": "A comma-separated list of data streams or data stream patterns. Supports wildcards (`*`)."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_data_stream_settings.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_data_stream_settings.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "Comma-separated list of data streams or data stream patterns"
+              "type": "list",
+              "description": "A comma-separated list of data streams or data stream patterns. Supports wildcards (`*`)."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_migrate_reindex_status.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_migrate_reindex_status.json
@@ -23,8 +23,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "The index or data stream name"
+              "type": "list",
+              "description": "Comma-separated list of index or data stream names."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_data_stream_mappings.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_data_stream_mappings.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "Comma-separated list of data streams or data stream patterns"
+              "type": "list",
+              "description": "A comma-separated list of data streams or data stream patterns."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_data_stream_settings.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_data_stream_settings.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "name": {
-              "type": "string",
-              "description": "Comma-separated list of data streams or data stream patterns"
+              "type": "list",
+              "description": "A comma-separated list of data streams or data stream patterns."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/logstash.get_pipeline.json b/rest-api-spec/src/main/resources/rest-api-spec/api/logstash.get_pipeline.json
@@ -26,8 +26,8 @@
           ],
           "parts": {
             "id": {
-              "type": "string",
-              "description": "A comma-separated list of Pipeline IDs"
+              "type": "list",
+              "description": "A comma-separated list of pipeline identifiers."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.delete_calendar_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.delete_calendar_job.json
@@ -24,8 +24,8 @@
               "description": "The ID of the calendar to modify"
             },
             "job_id": {
-              "type": "string",
-              "description": "The ID of the job to remove from the calendar"
+              "type": "list",
+              "description": "An identifier for the anomaly detection jobs. It can be a job identifier, a group name, or a comma-separated list of jobs or groups."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_datafeed_stats.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_datafeed_stats.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "datafeed_id": {
-              "type": "string",
-              "description": "The ID of the datafeeds stats to fetch"
+              "type": "list",
+              "description": "Comma-separated list of datafeed identifiers or wildcard expressions. If you do not specify one of these options, the API returns information about all datafeeds."
             }
           }
         },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_datafeeds.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_datafeeds.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "datafeed_id": {
-              "type": "string",
-              "description": "The ID of the datafeeds to fetch"
+              "type": "list",
+              "description": "Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the API returns information about all datafeeds."
             }
           }
         },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_filters.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_filters.json
@@ -26,8 +26,8 @@
           ],
           "parts": {
             "filter_id": {
-              "type": "string",
-              "description": "The ID of the filter to fetch"
+              "type": "list",
+              "description": "Comma-separated list of strings that uniquely identify a filter."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_jobs.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_jobs.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "job_id": {
-              "type": "string",
-              "description": "The ID of the jobs to fetch"
+              "type": "list",
+              "description": "Comma-separated list of identifiers for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. If you do not specify one of these options, the API returns information for all anomaly detection jobs."
             }
           }
         },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_trained_models.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_trained_models.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "model_id": {
-              "type": "string",
-              "description": "The ID of the trained models to fetch"
+              "type": "list",
+              "description": "The unique identifier of the trained model or a model alias.  You can get information for multiple trained models in a single API request by using a comma-separated list of model IDs or a wildcard expression."
             }
           }
         },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_trained_models_stats.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_trained_models_stats.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "model_id": {
-              "type": "string",
-              "description": "The ID of the trained models stats to fetch"
+              "type": "list",
+              "description": "The unique identifier of the trained model or a model alias. It can be a comma-separated list or a wildcard expression."
             }
           }
         },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.put_calendar_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.put_calendar_job.json
@@ -24,8 +24,8 @@
               "description": "The ID of the calendar to modify"
             },
             "job_id": {
-              "type": "string",
-              "description": "The ID of the job to add to the calendar"
+              "type": "list",
+              "description": "An identifier for the anomaly detection jobs. It can be a job identifier, a group name, or a comma-separated list of jobs or groups."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json
@@ -24,8 +24,8 @@
           ],
           "parts": {
             "index": {
-              "type": "string",
-              "description": "The rollup index or index pattern to obtain rollup capabilities from."
+              "type": "list",
+              "description": "Comma-separated list of data streams or indices to check for rollup capabilities. Wildcard (`*`) expressions are supported."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/security.delete_privileges.json b/rest-api-spec/src/main/resources/rest-api-spec/api/security.delete_privileges.json
@@ -24,8 +24,8 @@
               "description": "Application name"
             },
             "name": {
-              "type": "string",
-              "description": "Privilege name"
+              "type": "list",
+              "description": "Comma-separated list of privilege names."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/security.get_privileges.json b/rest-api-spec/src/main/resources/rest-api-spec/api/security.get_privileges.json
@@ -42,8 +42,8 @@
               "description": "Application name"
             },
             "name": {
-              "type": "string",
-              "description": "Privilege name"
+              "type": "list",
+              "description": "Comma-separated list of privilege names. If you do not specify this parameter, the API returns information about all privileges for the requested application."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/shutdown.get_node.json b/rest-api-spec/src/main/resources/rest-api-spec/api/shutdown.get_node.json
@@ -29,8 +29,8 @@
           ],
           "parts": {
             "node_id": {
-              "type": "string",
-              "description": "Which node for which to retrieve the shutdown status"
+              "type": "list",
+              "description": "Comma-separated list of nodes for which to retrieve the shutdown status"
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.repository_verify_integrity.json b/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.repository_verify_integrity.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "repository": {
-              "type": "string",
-              "description": "A repository name"
+              "type": "list",
+              "description": "Comma-separated list of snapshot repository names."
             }
           }
         }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/transform.get_transform.json b/rest-api-spec/src/main/resources/rest-api-spec/api/transform.get_transform.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "transform_id": {
-              "type": "string",
-              "description": "The id or comma delimited list of id expressions of the transforms to get, '_all' or '*' implies get all transforms"
+              "type": "list",
+              "description": "Comma-separated list of transform identifiers or wildcard expressions. You can get information for all transforms by using `_all`, by specifying `*` as the `<transform_id>`, or by omitting the `<transform_id>`."
             }
           }
         },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/transform.get_transform_stats.json b/rest-api-spec/src/main/resources/rest-api-spec/api/transform.get_transform_stats.json
@@ -20,8 +20,8 @@
           ],
           "parts": {
             "transform_id": {
-              "type": "string",
-              "description": "The id of the transform for which to get stats. '_all' or '*' implies all transforms"
+              "type": "list",
+              "description": "Comma-separated list of transform identifiers or wildcard expressions. You can get information for all transforms by using `_all`, by specifying `*` as the `<transform_id>`, or by omitting the `<transform_id>`."
             }
           }
         }

Original file line number	Diff line number	Diff line change
`@@ -20,8 +20,8 @@`
`20`	`20`	`],`
`21`	`21`	`"parts": {`
`22`	`22`	`"name": {`
`23`		`- "type": "string",`
`24`		`- "description": "The name of the template"`
	`23`	`+ "type": "list",`
	`24`	`+ "description": "Comma-separated list or wildcard expression of component template names used to limit the request."`
`25`	`25`	`}`
`26`	`26`	`}`
`27`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,8 +24,8 @@`
`24`	`24`	`],`
`25`	`25`	`"parts": {`
`26`	`26`	`"index": {`
`27`		`- "type": "string",`
`28`		`- "description": "The name of the index to scope the operation"`
	`27`	`+ "type": "list",`
	`28`	`+ "description": "Comma-separated list of index names to scope the operation"`
`29`	`29`	`}`
`30`	`30`	`}`
`31`	`31`	`}`
Original file line number	Diff line number	Diff line change
`@@ -26,8 +26,8 @@`
`26`	`26`	`],`
`27`	`27`	`"parts": {`
`28`	`28`	`"feature": {`
`29`		`- "type": "string",`
`30`		`- "description": "A feature of the cluster, as returned by the top-level health API"`
	`29`	`+ "type": "list",`
	`30`	`+ "description": "Comma-separated list of cluster features, as returned by the top-level health report API."`
`31`	`31`	`}`
`32`	`32`	`}`
`33`	`33`	`}`
Original file line number	Diff line number	Diff line change
`@@ -23,8 +23,8 @@`
`23`	`23`	`],`
`24`	`24`	`"parts": {`
`25`	`25`	`"index": {`
`26`		`- "type": "string",`
`27`		`- "description": "The index or data stream name"`
	`26`	`+ "type": "list",`
	`27`	`+ "description": "Comma-separated list of index or data stream names"`
`28`	`28`	`}`
`29`	`29`	`}`
`30`	`30`	`}`