From 167797cae1caa638c323f821b2ed2da59e393b8e Mon Sep 17 00:00:00 2001 From: Michael Dokolin Date: Tue, 8 Nov 2022 16:42:02 +0100 Subject: [PATCH] [Saved Objects] Add documentation covering hidden saved object types (#144647) --- dev_docs/tutorials/saved_objects.mdx | 6 +-- .../core/saved-objects-service.asciidoc | 40 +++++++++++++++++-- .../src/saved_objects_type.ts | 3 ++ 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/dev_docs/tutorials/saved_objects.mdx b/dev_docs/tutorials/saved_objects.mdx index f922077cb5e54..3ee9ca63e279d 100644 --- a/dev_docs/tutorials/saved_objects.mdx +++ b/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 diff --git a/docs/developer/architecture/core/saved-objects-service.asciidoc b/docs/developer/architecture/core/saved-objects-service.asciidoc index cc669be8ec9fa..c866d111bd1b6 100644 --- a/docs/developer/architecture/core/saved-objects-service.asciidoc +++ b/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 <> 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 diff --git a/packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts b/packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts index b26be6f8bfb1a..e36212e7913f3 100644 --- a/packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts +++ b/packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts @@ -26,6 +26,9 @@ export interface SavedObjectsType { /** * 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}. */