Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Nov 8, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e07fda
Add documentation covering hidden saved object types
dokmic Nov 4, 2022
ceacf51
Update TSDoc for the hidden property
dokmic Nov 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions dev_docs/tutorials/saved_objects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
Expand Down
40 changes: 37 additions & 3 deletions docs/developer/architecture/core/saved-objects-service.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}.
*/
Expand Down