[Docs] Clarify that payload of import/export APIs should be treated as opaque #159453
Labels
documentation
Feature:Saved Objects Management
Team:Core
Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc
While the path, query paramaters and body format (ndjson) are stable, the individual saved object records are not stable. Between versions we can add, remove or change fields. We have observed some users integrations breaking because they were indirectly relying on the format of the individual records instead of treating them as opaque.
As a concrete example we've seen users use a validation schema to process the output of the export API and this validation would drop unknown fields. When, inevitably, a new field gets introduced it's silently dropped causing unexpected failures.
We should clearly document how users should integrate into this API to help them avoid these problems.
See:
https://www.elastic.co/guide/en/kibana/current/dashboard-import-api.html
https://www.elastic.co/guide/en/kibana/current/saved-objects-api-export.html
The text was updated successfully, but these errors were encountered: