[DOCS] Add descriptions to API spec files

[jrodewig]

Tracking issue for track doc updates to specification files. To prevent duplicated work, leave your name beside a namespace/API you start working on.

It is recommended to prioritize APIs that are listed as "public" instead of "blocked" in the serverless plans: https://docs.google.com/spreadsheets/d/1xFrpFP1dARey8A1QkAoC7JJCGhAZFexMLpRTeY9PAos/

API namespace inventory:

• _global (we should probably subdivide these into distributed- and search-related APIs)
  • bulk [DOCS] Adds description to global APIs part 1 #2269
  • close_point_in_time/open_point_in_time [DOCS] Adds description to global APIs part 1 #2269
  • create [DOCS] Adds description to global APIs part 2 #2270
  • delete [DOCS] Adds description to global APIs part 2 #2270
  • delete_by_query/delete_by_query_rethrottle/update_by_query/update_by_query_rethrottle [DOCS] Adds description to global APIs part 2 #2270
  • delete_script/get_script/put_script/scripts_painless_execute [DOCS] Adds description to global APIs part 2 #2270
  • exists/exists_source [DOCS] Adds description to global APIs part 3 #2271
  • explain [DOCS] Adds description to global APIs part 3 #2271
  • index [DOCS] Adds description to global APIs part 3 #2271
  • msearch_template [DOCS] Adds description to global APIs part 3 #2271
  • mtermvectors/termvectors
  • reindex_rethrottle [DOCS] Adds description to global APIs part 3 #2271
  • render_search_template [DOCS] Adds description to global APIs part 3 #2271
  • search_shards [DOCS] Adds description to global APIs part 3 #2271
  • search_template [DOCS] Adds description to global APIs part 3 #2271
  • search Add descriptions for Search API #2171
  • queries [DOCS] Add descriptions for queries A-G #2204 Add descriptions for queries H-Q #2213 Add descriptions for queries R-W #2217
  • aggs [DOCS] Add descriptions for aggs A-F #2225 [DOCS] Add descriptions for remaining aggs #2237
  • suggesters [DOCS] Add descriptions for suggesters #2246
• indices
  • get_settings Add descriptions for index settings APIs #2174
  • put_settings Add descriptions for index settings APIs #2174
  • ... (list to be completed)
• async_search Add descriptions for async search #2115
• autoscaling BLOCKED (marked as done)
• cat Add descriptions for cat APIs #2124, Add descriptions for more cat APIs #2138, Add descriptions for final cat APIs #2139
• ccr BLOCKED (marked as done)
• cluster Add descriptions to pending cluster tasks API #2150, Add descriptions for cluster settings and cluster stats #2154
• component_templates Add descriptions for component templates #2155
• count [DOCS] Descriptions for the count API #2265
• dangling_indices BLOCKED (marked as done)
• data stream Add data stream descriptions #2163, Add descriptions for migrate, modify, and data stream stats #2179
• enrich [DOCS] Adds descriptions for Enrich APIs #2215
• eql [DOCS] Adds descriptions for EQL APIs #2216
• features BLOCKED (marked as done)
• fleet INTERNAL (marked as done)
• graph [DOCS] Adds descriptions for the Graph API #2221
• ilm BLOCKED (marked as done)
• indices [DOCS] Adds descriptions to index APIs (A-F) #2226, [DOCS] Adds descriptions to index APIs (G-Z) #2230
• ingest [DOCS] Adds descriptions to ingest APIs #2236
• license only the GET license API is PUBLIC, the rest is BLOCKED (marked as done, GET license is addressed)
• logstash [DOCS] Adds descriptions to Logstash APIs #2240
• migration BLOCKED (marked as done)
• ml https://github.com/elastic/stack-docs/issues/1845; [DOCS] Adds descriptions to ML APIs #2245
• monitoring BLOCKED (marked as done)
• nodes [DOCS] Adds description to Node APIs #2248
• reindex [DOCS] Add descriptions for the reindex API #2247
• rollup [DOCS] Adds description to Rollup APIs #2253
• search_application [DOCS] Adds description to the Search Application APIs #2266
• searchable_snapshots INTERNAL (marked as done)
• security Add description to Authenticate API #2152 Add descriptions for API key API #2167 most of the endpoints are addressed, the rest is INTERNAL (marked as done)
• shutdown BLOCKED (marked as done)
• slm BLOCKED (marked as done)
• snapshot INTERNAL (marked as done)
• sql [DOCS] Descriptions for SQL APIs #2264
• ssl INTERNAL (marked as done)
• tasks [DOCS] Descriptions for tasks APIs #2263
• text_structure
• transform
• watcher not working on serverless at least for now (marked as done)
• xpack INTERNAL (marked as done)

Other utility files to review:

• _spec_utils
• _types

[jrodewig]

For now, let's prioritize this work so that we focus on APIs we plan to expose publicly for Serverless. The spreadsheet contains an informal list we can use planning:

https://docs.google.com/spreadsheets/d/1dAt-eZ4zvZVXjTnpCCkMfhCzPXymGGCjOCxeNijbiRc/edit#gid=210925944

Happy to move that work into a separate issue if preferred. Thanks!

Edit: I overlooked the spreadsheet in the issue description before posting this. Based on this Slack conversation, that's the most up-to-date sheet for now. Ignore this comment.

[abdonpijpelink]

All public APIs have been documented. 🎉 Closing this issue.

We'll follow-up with another issue for the internal and blocked APIs.

[szabosteve]

You can find the follow-up issue here: #2273