[BUG] Cluster State API is undocumented and unavailable in clients

[dbwiddis]

Describe the bug

Coming from https://github.com/opensearch-project/OpenSearch/issues/7066#issuecomment-1501541654

Internally to OpenSearch, the cluster state is retrieved by handling the ClusterStateAction / TransportClusterStateAction / ClusterStateRequest / ClusterStateResponse implementations. The RestClusterStateAction exposes the API (?) as:

• /_cluster/state
• /_cluster/state/{metric}
• /_cluster/state/{metric}/{indices}

However, there is no (0 / zero / null) documentation of this API on the OpenSearch website. Entering "/_cluster/state" in the search bar at https://opensearch.org/ gives 17 responses, out of which zero contain the text "/_cluster/state".

Entering "/_cluster/state" and "OpenSearch" as key words into your favorite search engine give no results on https://opensearch.org/ (other than one of the previous 17 that doesn't actually include that text). There are some third-party references to the API, a reference to the API at ElasticSearch, and inclusion as a "common" API request on AOS documentation page.

More importantly, this "API" is not accessible via OpenSearch clients. Clients are spec-driven, but the Cluster APIs do not include it. While it's possible to reverse-engineer the ClusterStateRequest to construct a raw endpoint for performRequest() on the clients, the returned response is just JSON and parsing it into a ClusterStateResponse is an exercise in futility.

Expected behavior

1. The API is documented on the OpenSearch website. (Definitely.)
2. The ClusterStateRequest/ClusterStateResponse objects are usable in OpenSearch clients in all languages. (Maybe not, see comments below.)