[API]: Clarify GET / response on Serverless

[ppf2]

Was the documentation helpful?

No

What documentation page is affected

https://www.elastic.co/docs/api/doc/elasticsearch-serverless/group/endpoint-info

Description

Many users are confused about the version number returned when running [GET /](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/group/endpoint-info) on Serverless.

On Serverless, this endpoint will always return 8.11.0 as the version number and it is expected. Serverless offers automatic upgrades. Version is no longer something the user manages.

For backwards compatibility reasons for the GET / API, we need to return a semantic version and we decided to use the latest Stack version at the time first Serverless api version was released. Hence we return 8.11.0. It does not mean that automatic version upgrade functionality is broken on Serverless.

Users can simply ignore the version number in this API call.

Please update the example and the description of the version number at https://www.elastic.co/docs/api/doc/elasticsearch-serverless/group/endpoint-info to explain that the version number can be ignored on Serverless. Thx!

@KOTungseth

[leemthompo]

cc @rjernst if have any inputs on how we address this in the docs :)

[rjernst]

I would take this a step further and say the docs should deter users from this API altogether in serverless. Nothing in the response is useful to users, it is provided strictly as a backwards compatibility mechanism for old 8.x clients trying to connect to serverless.

With that said, these docs are generated from the same API spec used with on-prem ES. Is it possible to have 2 definitions, one for serverless and one for on-prem? Then we could document the individual elements as well, explaining the single value returned in serverless for each.

[leemthompo]

I would take this a step further and say the docs should deter users from this API altogether in serverless. Nothing in the response is useful to users, it is provided strictly as a backwards compatibility mechanism for old 8.x clients trying to connect to serverless.

Just thinking about time management here, I think the highest cost/benefit here would be to just put a big warning that this API is meaningless for serverless users and is available purely for internal BWC

With that said, these docs are generated from the same API spec used with on-prem ES. Is it possible to have 2 definitions, one for serverless and one for on-prem? Then we could document the individual elements as well, explaining the single value returned in serverless for each.

Is this worth the effort knowing that we are going to do away with standalone serverless docs eventually, and the API is not technically blocked for serverless users? I don't see the value of investing time in explaining why each individual element of the response object isn't useful, when we should just use a blanket statement. LMKWYT!