[Serverless]: Include authorization header example in all API curl examples

[ppf2]

Serverless Docs

Elasticsearch Serverless API

Description

A customer couldn't figure out how to pass in the API key to make Serverless API calls.

While this information is in the getting started guide, they landed directly in the Serverless API reference which does not provide such example.

Can we update all curl examples for Serverless API calls to include the API Key header?

  -H "Authorization: ApiKey ${API_KEY}" 

Thx!

Resources and additional context

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

[lcawl]

I've created elastic/elasticsearch-specification#3198 so that the Elasticsearch API docs will have an introductory "Authentication" page similar to https://www.elastic.co/docs/api/doc/serverless/authentication.

It seems like the only way to get the Authorization header parameter added to the automatically-generated examples is by explicitly adding it to the specification (which is how we get the elastic-api-version header to appear in Kibana APIs like https://www.elastic.co/docs/api/doc/serverless/operation/operation-get-alerting-rule-id). However further investigation is required to determine where we can add header parameters in https://github.com/elastic/elasticsearch-specification at this time.

It's worth noting that we didn't include the headers when you copy as curl in our old API docs either.

[lcawl]

https://www.elastic.co/docs/api/doc/elasticsearch-serverless/authentication is now live.

Per slack discussions with the elasticsearch-specification folks, there isn't currently support for adding headers in the specifications. "The only thing we currently do with headers is using the Content-Type and Accept headers from the JSON specification: https://github.com/elastic/elasticsearch-specification/blob/1552e8565ee672b999442f67a065093ca339966d/compiler/src/steps/add-content-type.ts#L34-L40". That support will eventually be required for elastic/elasticsearch-specification#2747, so we can revisit whether we want the authorization values pushed down to every operation at that time too.