[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