Support experimental APIs

[jloleysens]

Pending design and agreement on how this will be represented in OAS CC @lcawl

[elasticmachine]

Pinging @elastic/kibana-core (Team:Core)

[lcawl]

FYI Bump.sh already supports x-beta per https://docs.bump.sh/help/specification-support/doc-beta/ and we've requested an extension like x-tech-preview. I'll update as soon as the latter is available.

[lcawl]

FYI This information was added to the Elasticsearch OpenAPI documents per elastic/elasticsearch-specification#2716

[lukeelmers]

related #179170

[lcawl]

Based on the way the Elasticsearch specification has implemented @availability, it seems like the lifecycle states might vary for serverless and stateful variations of API. For example in IndicesGetDataLifecycleRequest.ts:

/**
* Get data stream lifecycles.
* Retrieves the data stream lifecycle configuration of one or more data streams.
* @rest_spec_name indices.get_data_lifecycle
* @availability stack since=8.11.0 stability=stable
* @availability serverless stability=stable visibility=public
*/

I do not see any examples yet where it's "experimental" in one and "stable" in the other, but if that's possible it affects how we might want to handle this in the API doc automation. Especially if we one day manage to have both serverless and stateful details in a single document. IMO if it's possible to make this work from the code, we should consider outputing it in the docs in a specification extension like this:

       "x-availability": {
         "stack": {
           "stability": "beta",
           "since": "7.7.0"
         },
         "serverless": {
           "stability": "experimental",
           "since": "2023-10-31"
         } 
       }

Alternatively, if it makes branching or implementation easier, split into two extensions:

    "x-availability-stack": {
           "stability": "beta",
           "since": "7.7.0"
         },
    "x-availability-serverless": {
           "stability": "experimental",
           "since": "2023-10-31"
        } 

I think we'd need to have this at the endpoint level at a minimum (preferrably operation level). Theoretically it would be nice to have even down to the parameter and property level (e.g. in https://github.com/elastic/elasticsearch-specification/blob/a00834bb0f50a10c39858a4b971c84cbe4b6aa8b/specification/_global/field_caps/types.ts#L56 ) since such components could have different availabilities. More info in elastic/elasticsearch-specification#2804

[jloleysens]

Related elastic/elasticsearch-specification#2989