Security Api Key API feedback

[codebrain]

This ticket has been raised from implementing the security API key functionality in the .NET client 6.7.0 - elastic/elasticsearch-net#3684

Documentation

• https://www.elastic.co/guide/en/elasticsearch/reference/7.0/security-api-invalidate-api-key.html
  • The Request Body documentation for the realm_name and username mentions the parameters api_key_id and api_key_name, but these parameters are not declared, should they be id and name?

API usage

• The create API key method always requires role_descriptors, even if empty. For example:

POST /_security/api_key
{
  "name": "my-api-key",
  "role_descriptors": {}
}

It would be more favourable if this parameter could be null or omitted altogether and for the behaviour to still be the same as if an empty object declaration {} was provided. The .NET client default behaviour is to omit properties that are null (by default), having to specify an empty value requires workarounds

https://github.com/elastic/elasticsearch-net/blob/41fdbb1532f5c1da49013383bc16ba4503d85d94/src/Nest/XPack/Security/ApiKey/CreateApiKey/CreateApiKeyRequest.cs#L37

https://github.com/elastic/elasticsearch-net/blob/41fdbb1532f5c1da49013383bc16ba4503d85d94/src/Nest/XPack/Security/ApiKey/CreateApiKey/CreateApiKeyRequest.cs#L50

• Interactions with the API require a user with the superuser role.

https://github.com/elastic/elasticsearch-net/blob/41fdbb1532f5c1da49013383bc16ba4503d85d94/src/Tests/Tests/XPack/Security/ApiKey/SecurityApiKeyTests.cs#L63

REST JSON specs

• The specifications have dropped the xpack.* prefix in the filename and specification key name. Not an issue per se, but it is inconsistent with the other APIs in 6.7.0

[elasticmachine]

Pinging @elastic/es-security

[bizybot]

Thanks @codebrain , I will work on fixing the documentation and the usage.
The API key privileges is in progress work and will update this issue once it is merged.