[Saved Objects] Add documentation covering hidden saved object types (#144647)

dev_docs/tutorials/saved_objects.mdx

@@ -18,7 +18,7 @@ import { SavedObjectsType } from 'src/core/server';
 
 export const dashboardVisualization: SavedObjectsType = {
   name: 'dashboard_visualization', [1]
-  hidden: false,
+  hidden: true,
   namespaceType: 'multiple-isolated', [2]
   mappings: {
     dynamic: false,
@@ -38,8 +38,8 @@ export const dashboardVisualization: SavedObjectsType = {
 };
 ```
 
-[1] Since the name of a Saved Object type forms part of the url path for the public Saved Objects HTTP API, 
-these should follow our API URL path convention and always be written as snake case.
+[1] Since the name of a Saved Object type forms part of the URL path for the public Saved Objects HTTP API,
+these should follow our API URL path convention and always be written in snake case.
 
 [2] This field determines "space behavior" -- whether these objects can exist in one space, multiple spaces, or all spaces. This value means
 that objects of this type can only exist in a single space. See

docs/developer/architecture/core/saved-objects-service.asciidoc

@@ -45,7 +45,7 @@ import { SavedObjectsType } from 'src/core/server';
 
 export const dashboardVisualization: SavedObjectsType = {
   name: 'dashboard_visualization', // <1>
-  hidden: false,
+  hidden: true,
   namespaceType: 'multiple-isolated', // <2>
   mappings: {
     dynamic: false,
@@ -64,9 +64,9 @@ export const dashboardVisualization: SavedObjectsType = {
   },
 };
 ----
-<1> Since the name of a Saved Object type forms part of the url path for the
+<1> Since the name of a Saved Object type may form part of the URL path for the
 public Saved Objects HTTP API, these should follow our API URL path convention
-and always be written as snake case.
+and always be written in snake case.
 <2> This field determines "space behavior" -- whether these objects can exist in one space, multiple spaces, or all spaces. This value means
 that objects of this type can only exist in a single space. See <<sharing-saved-objects,Sharing Saved Objects>> for more information.
 
@@ -268,6 +268,40 @@ as expected with all possible input documents. Given how simple it is to test
 all the branch conditions in a migration function and the high impact of a bug
 in this code, there's really no reason not to aim for 100% test code coverage.
 
+==== Type visibility
+It is recommended that plugins only expose Saved Object types that are necessary.
+That is so to provide better backward compatibility.
+In case when the type is not hidden, it will be exposed via the global Saved Objects HTTP API.
+That brings the limitation of introducing backward incompatible changes as there might be a service consuming the API.
+
+This is a formal limitation not prohibiting backward incompatible changes in the migrations.
+But in case of such changes on the hidden types, they can be resolved and encapsulated on the intermediate layer in the plugin API.
+
+Hence, the main idea is that all the interactions with the Saved Objects should be done via the plugin API rather than via the Saved Objects HTTP API.
+
+By default, the hidden types will not be accessible in the Saved Objects client.
+To make them accessible, they should be explicitly listed in the `includedHiddenTypes` parameters upon client creation.
+
+[source,typescript]
+----
+import { CoreStart, Plugin } from '@kbn/core/server';
+
+class SomePlugin implements Plugin {
+  // ...
+
+  public start({ savedObjects }: CoreStart) {
+    // ...
+
+    const savedObjectsClient = savedObjects.getScopedClient(
+      request,
+      { includedHiddenTypes: ['dashboard_visualization'] }
+    );
+
+    // ...
+  }
+}
+----
+
 === Client side usage
 
 ==== References

packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts

@@ -26,6 +26,9 @@ export interface SavedObjectsType<Attributes = any> {
   /**
    * Is the type hidden by default. If true, repositories will not have access to this type unless explicitly
    * declared as an `extraType` when creating the repository.
+   * It is recommended to hide the type for better backward compatibility.
+   * The hidden types will not be automatically exposed via the HTTP API.
+   * Therefore, that should prevent unexpected behavior in the client code, as all the interactions will be done via the plugin API.
    *
    * See {@link SavedObjectsServiceStart.createInternalRepository | createInternalRepository}.
    */