Why are the Kibana REST APIs marked as experimental?

[boskjoett (Bo Christian Skjøtt)]

When I look at the Kibana 7.13.1 REST API documentation, for example

Create or update role API | Kibana Guide [7.13] | Elastic

then all the API endpoints are marked [Experimental].
Why is the Kibana REST API experimental? Do you not recommend customers to use them?

Also on this page Kibana role management APIs | Kibana Guide [master] | Elastic
it says "WARNING: Do not use the Elasticsearch role management APIs to manage Kibana roles."

It would be nice with a little more explanation about what this means. I find it very hard to understand when to use roles in Kibana versus roles in Elasticsearch - when you set this up using the REST APIs.

[rashmi (kulkarni)]

There is no pre-defined snippet, but I can explain about the role management API's . The Elasticsearch role management APIs require you to understand Kibana’s application privileges format, and that is something we treat as an implementation detail. While we haven’t changed it all that much, we don’t guarantee that it will be stable across releases (even though in practice making a breaking change here would be problematic for us in a minor). The way Kibana uses the application privileges format is not all that intuitive, either.
For that reason, we encourage the use of Kibana Role APIs whenever you are creating a role that grants access to Kibana. Kibana’s APIs make our privileges easier to consume, and hide a lot of the complexity for you. They are only marked experimental because we were leaving ourselves room to make breaking changes if necessary, but I don’t expect that we will remove these at any point in the near future. Hope this helps.

Thanks!
Rashmi