[OE] Stabilize and document saved objects API

[kavilla]

Is your feature request related to a problem? Please describe.

We have a lot of issues with the saved objects API even though it's a fundamental item of OpenSearch Dashboards. The API is being used more and more even though it technically never was made a production feature.

Current open issues related to the saved objects API:

• Fix type errors from Saved Object Management changes #3023
• How can I pre-populate the saved objects when running docker-compose? #3195
• [Docs] OpenSearch Dashboards documentation gaps #2132
• Confusing opensearch dashboard import API #1723
• [Docs] Dev docs for using Saved Objects & Embeddables #1700
• [Research] Metadata and Saved Objects research #1464
• type mismatch issue in src/core/server/saved_objects #1360
• [BUG]: Cannot create index_pattern via API #910
• Saved Objects API as production feature #987
• Saved-Objects export and import formats should be interchangeable #1526
• [FEATURE] Offer OpenSearch Dashboards APIs as Public APIs #1647
• [BUG] Support duplicate index pattern name #5946
  • this was merged but this only addresses the side effect but in reality users should not be able to upload identically saved objects

Describe the solution you'd like

• Stabilize saved objects API
• Address gaps and provide more validation with in the API
• More testing
• Explicit documentation
  • Perhaps adding writing an SDK so developers can utilize the saved objects API

Describe alternatives you've considered

n/a

Additional context

n/a

[BlaiseSaunders]

#6340

Another relevant item for this list 😄

[seraphjiang]

@Flyingliuhub @bandinib-amzn @BionIT @CCongWang this is critical, let's see how could we help.

[Swiddis]

Adding onto this: the saved objects API is a critical dependency for Integrations and we regularly are exporting/tweaking/reimporting them. This is made much more difficult by the lack of documentation on how different objects are serialized and their behavior when values are changed -- most of what our team knows about this has been found through trial-and-error. We maintain exported dashboards, visualizations, and searches as code and have tools that auto-generate saved objects or parse them for nicer debugging info.

All that to say, +1 for stabilizing the APIs and getting traction on these issues :)

[kavilla]

#4695

[Swiddis]

Any progress on this? We could consider enhancing the existing docs and promoting the described endpoint to stable, I'm not sure what breaking changes are upcoming but since April the amount of features depending on this endpoint has only been growing.