[Feedback]: Elastic-api-version in the Kibana API examples

[lcawl]

Was the documentation helpful?

Yes

What documentation page is affected

Generated API documentation for Kibana that include a request body. For example https://www.elastic.co/docs/api/doc/kibana/operation/operation-2fapi-2fsecurity-2frole-2f-7bname-7d-2

Description

Per feedback from @sophiec20 the curl examples look like this:

curl \
 -X PUT https://localhost:5601/api/security/role/{name} \
 -H "Content-Type: application/json; Elastic-Api-Version=2023-10-31" \
 -H "elastic-api-version: 2023-10-31" \
 -H "kbn-xsrf: true"

That Content-Type: application/json; Elastic-Api-Version=2023-10-31 is derived from the way we qualified the requests and responses to make it clear which version the request and response pertain to. However it's not something that should appear in the curl commands.

It seems like we need to either (1) override the automated curl examples with custom examples (https://docs.bump.sh/help/specification-support/doc-code-samples/) or (2) remove the Elastic-Api-Version=2023-10-31 qualifier from the automated output and find some other way to indicate which version header value each request and response is associated with.

ES_FEEDBACK_ID: lFtk2pIBWCMSeP1oc2YL

[sophiec20]

This also causes responsive issues... Because of the length of text, there is overflow in the BODY section at narrower page widths. This does not occur afaict in the elasticsearch-serverless api docs.

If the elasticsearch docs do not specify Elastic-Api-Version=2023-10-31 .. then why do the kibana docs?

[lcawl]

This does not occur afaict in the elasticsearch-serverless api docs.
If the elasticsearch docs do not specify Elastic-Api-Version=2023-10-31 .. then why do the kibana docs?

This relates to the outstanding elastic/elasticsearch-specification#2747
The outstanding tasks IMO are to:

1. Verify that versioning strategy is unchanged from original assumptions.
2. Confirm whether running -H "Content-Type: application/json; Elastic-Api-Version=2023-10-31" causes errors
   • If yes, find alternative valid method in OpenAPI for encoding multiple alternative requests and responses based on header value
   • If no, describe this convention in introductory topics to avoid confusion.
3. Follow up with Bump.sh on wrapping issue.

[lcawl]

I ran a local test against a default-8.17.0-8.x-235 environment, using one of the examples in https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-actions-connector-id :

curl \
 -X POST https://localhost:5601/api/actions/connector \
 -H "Content-Type: application/json; Elastic-Api-Version=2023-10-31" \
 -H "elastic-api-version: 2023-10-31" \
 -H "kbn-xsrf: true" -d '{
  "name": "email-connector-1",
  "config": {
    "from": "[email protected]",
    "host": "https://example.com",
    "port": 1025,
    "secure": false,
    "hasAuth": true,
    "service": "other"
  },
  "secrets": {
    "user": "username",
    "password": "password"
  },
  "connector_type_id": ".email"
}' --cacert ca.crt -u elastic

It completes successfully:

{"id":"2cf8885c-d390-4942-b475-66b773d26466","name":"email-connector-1","config":{"from":"[email protected]","host":"https://example.com","port":1025,"secure":false,"hasAuth":true,"service":"other","tenantId":null,"clientId":null,"oauthTokenUrl":null},"connector_type_id":".email","is_preconfigured":false,"is_deprecated":false,"is_missing_secrets":false,"is_system_action":false}

Therefore the header information seems to be extraneous but not erroneous.

[lcawl]

elastic/kibana#202923 undertakes the removal of the version header info for now.