Document advanced settings API

[tylersmalley]

We should add documentation for this API and tag experimental.

[epixa]

What is the advanced setting API versus the saved object API?

[tylersmalley]

@epixa this is the API used for the advanced settings in the UI.

I usually direct folks to inspect the request made by using the UI.

POST http://localhost:5601/api/kibana/settings
{"changes":{"defaultIndex":"logstash-*"}}

[epixa]

I'm not sure if this is really an API we want to expose to people. The whole changes thing would be completely unprecedented, not RESTful, and not how we'd design this API if our intention was for people to consume it. People can use the documented saved object APIs for config as a whole, and we can build a REST api specifically for updating individual advanced settings if we want.

[gchaps]

@epixa Do we have a decision on whether we are going to document this API? If not, can we close this issue?

[epixa]

I don't think we can reasonably encourage any person to use these APIs directly as they are today. I propose we add an issue for a proper settings API. @joshdover do you agree?

[joshdover]

Agreed. If anything, we should just point users to the SavedObjects API in the meantime since that can be used as well (only tricky part is the object ID is the Kibana version number).

[cwurm]

How would the SavedObjects API be used to change an Advanced Setting (e.g. to change siem:defaultIndex as asked in #51454)?

[tsullivan]

Would the Saved Objects API be able to validate user inputs of the settings, for example check that dateFormat:tz is set to a valid time zone, as asked in #58437