[Saved objects] Prepare SO management for versionable types #149495

jloleysens · 2023-01-25T11:05:04Z

Summary

Part of preparing HTTP APIs and associated interfaces for versioning:

Add domain-specific interfaces to the saved object management plugin
- Add a V1 interface of domain types to common
- Remove use of deprecated SavedObject type from public
Follows on from [Saved Objects Management] Encapsulate saved objects deletion behind an API endpoint #148602

Related #149098

Fixes #149495

… HTTP API endpoint interfaces

…fix'

jloleysens · 2023-01-31T12:03:03Z

@TinaHeiligers @rudolf @pgayvallet I've tried to incorporate feedback. Let me know what you think of the current iteration:

using namespace for types (v1)
using latest.ts file as an optimisation on the export type CoolName = ... now that we removed V1 suffix from names.

src/plugins/saved_objects_management/common/types/README.md

TinaHeiligers

The recent changes look good to me!

TinaHeiligers · 2023-02-02T00:50:08Z

src/plugins/saved_objects_management/common/types/v1.ts

+ * Saved Object Management metadata associated with a saved object. See
+ * {@link SavedObjectWithMetadata}.
+ */
+export interface SavedObjectMetadata {


Are the types that don't have the V1 suffix not expected to change at all? I'd expect to see all the types and interfaces declared in this file to only be the ones that change.

Shared types/interfaces that we can guarantee will never change could live elsewhere, for example, in the main types file.

Keeping the versioned-types file as small as possible helps us monitor changes over time.

TinaHeiligers · 2023-02-02T00:53:02Z

src/plugins/saved_objects_management/public/lib/bulk_delete_objects.ts

-    }
-  );
+  objects: v1.BulkDeleteBodyHTTP
+): Promise<v1.BulkDeleteResponseHTTP> {


Should we indicate these are for internal purposes only?

/* @internal */ export function bulkDeleteObjects(...

TinaHeiligers

It's so hard to get it right the first time, thanks for keeping up!
For now, I'm ok with the proposed changes.

kibana-ci · 2023-02-02T15:47:49Z

💚 Build Succeeded

Buildkite Build
Commit: 026665e

Metrics [docs]

Module Count

Fewer modules leads to a faster build time

id	before	after	diff
`savedObjectsManagement`	79	78	-1

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`savedObjectsManagement`	117	140	+23

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
`savedObjectsManagement`	85.2KB	85.2KB	+1.0B

Public APIs missing exports

Total count of every type that is part of your API that should be exported but is not. This will cause broken links in the API documentation system. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats exports for more detailed information.

id	before	after	diff
`savedObjectsManagement`	0	2	+2

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
`savedObjectsManagement`	19.4KB	19.3KB	-67.0B

Unknown metric groups

API count

id	before	after	diff
`savedObjectsManagement`	130	154	+24

References to deprecated APIs

id	before	after	diff
`savedObjectsManagement`	57	43	-14

History

💚 Build #105081 succeeded e23f91e
💚 Build #104166 succeeded 542b448
💔 Build #104148 failed fba8964
💚 Build #104113 succeeded 681d372
💚 Build #103667 succeeded f05ac13
💚 Build #103377 succeeded f1074aa

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

jloleysens · 2023-02-02T16:01:00Z

@TinaHeiligers @rudolf @pgayvallet thanks for all the input so far! @pgayvallet and I spoke about the current approach:

For now, lets go with the general recommendation that you should version a collection/namespace of types, instead of individual types.

Ultimately, plugins can version domain types however they choose, but the assumption is that it will be common that a set of interfaces change together.

In the case of SO management plugin we have a few domains AFAICT:

saved object (with metadata)
relations
import/export (although this mostly lives in our core packages)

We could group these in individual domains that are versioned independently (where if one type changes, naturally others will change). So we could have domain: relationsV1.Relation and relationsV1.GetRelationHTTP, then relationsV2.Relation and relationsV2.GetRelationHTTP.

However, the current API surface area is quite small and I'm not sure this will yield value for that level of effort. So everything just lives under an unqualified v1 (or v2).

See the README.md for an explanation. Let me know what you think, but based on current comments I think we are aligned. Happy to make revisions in follow ups.

jloleysens · 2023-02-02T16:09:26Z

We can capture details not represented here when working on #149929

## Summary This PR addresses 4 TODOs identified in #149495. We address these TODOs by taking a closer look at actual use of flagged fields in public code: 1. `FindQueryHTTP['namespaceType']`: Probably OK to directly expose this as it seems highly unlikely this value will change soon... We should also be able to version it since it is a well known set. 2. `FindQueryHTTP['search']`: looks like it is allowing users to enter _any_ search value against SO attribs. However, this functionality is constrained because it only takes a search term and runs it against a server-side determined search field. The risk is that consumers of the server-side functionality do not keep their default search field up-to-date. 3. `FindQueryHTTP['fields']`: Our UI only ever passes in `id` here. We should consider a follow up PR to add some counter telemetry to track usage of this option and consider removing it entirely. 4. `FindQueryHTTP['sortField']`: Lock this down to a well known set of values (probably the riskiest change here). --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

## Summary Adds a dev docs guide for the core-approved versioning strategy. This strategy is subject to some iteration but is based on the work we did for the Saved Objects Management plugin in #149495. Closes #149929 ## How to test 1. Run `./scripts/dev_docs.sh` 2. Navigate to "Versioning interfaces" in the side nav menu --------- Co-authored-by: Luke Elmers <lukeelmers@gmail.com>

## Summary Adds a dev docs guide for the core-approved versioning strategy. This strategy is subject to some iteration but is based on the work we did for the Saved Objects Management plugin in elastic#149495. Closes elastic#149929 ## How to test 1. Run `./scripts/dev_docs.sh` 2. Navigate to "Versioning interfaces" in the side nav menu --------- Co-authored-by: Luke Elmers <lukeelmers@gmail.com>

jloleysens added 6 commits January 25, 2023 11:58

STEP 1: refactor to not use the public SO HTTP APIs!

b427c20

STEP 2: Build a versionable type layer for your domain types AND your…

3d1901d

… HTTP API endpoint interfaces

body type -> query type

849971c

update public code to use HTTP API interfaces

b2374bd

added delete route types

adeb24e

actually register the delete route

cf77557

jloleysens added Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc Feature:Saved Objects release_note:skip Skip the PR/issue when compiling release notes Feature:Saved Objects Management labels Jan 25, 2023

jloleysens and others added 18 commits January 26, 2023 15:20

Merge branch 'main' into saved-objects-man-versioned-apis

9962f8d

remove unused route

935ad21

fix usage of bulk response v1

225ec1d

update find related types

04fe02d

remove dependence on public SavedObject type

0782ba8

added versioned types for bulk delete body and response

7ffd75a

use bulk response type server side

c35b104

type the scroll body response

969507f

use the TS type keyword where appropriate in server routes

8806c50

[CI] Auto-commit changed files from 'node scripts/lint_ts_projects --…

bff8a0f

…fix'

Merge branch 'main' into saved-objects-man-versioned-apis

f9b9839

Find API: savedObjects -> saved_objects

ba2df2e

fix another deprecated import and update the domain-specific types

d8bf1f9

only send the necessary values over the wire

05c586e

added per_page and page values

697f6ca

Merge branch 'main' into saved-objects-man-versioned-apis

c7e35d3

remove keys to camelcase conversion

f9b5bcb

refactor savedObjects -> saved_objects in Jest test

8f706f1

jloleysens marked this pull request as ready for review January 27, 2023 14:09

jloleysens requested a review from a team as a code owner January 27, 2023 14:09

jloleysens added 3 commits January 31, 2023 13:04

use unknown instead of any

fba8964

remove use of non-existing type

4aa0459

added README.md

542b448

TinaHeiligers reviewed Feb 1, 2023

View reviewed changes

src/plugins/saved_objects_management/common/types/README.md Outdated Show resolved Hide resolved

TinaHeiligers reviewed Feb 1, 2023

View reviewed changes

src/plugins/saved_objects_management/common/types/README.md Outdated Show resolved Hide resolved

TinaHeiligers reviewed Feb 1, 2023

View reviewed changes

TinaHeiligers reviewed Feb 2, 2023

View reviewed changes

TinaHeiligers approved these changes Feb 2, 2023

View reviewed changes

jloleysens and others added 3 commits February 2, 2023 13:58

Merge branch 'main' into saved-objects-man-versioned-apis

e23f91e

version all types together

bf02a74

remove V1

026665e

jloleysens merged commit df809bd into elastic:main Feb 2, 2023

jloleysens deleted the saved-objects-man-versioned-apis branch February 2, 2023 16:02

kibanamachine added v8.7.0 backport:skip This commit does not require backporting labels Feb 2, 2023

This was referenced Feb 9, 2023

[Versioned APIs] Versioned interfaces dev docs guide #150705

Merged

[Saved Object Management] Address v1 HTTP API TODOs #150892

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Saved objects] Prepare SO management for versionable types #149495

[Saved objects] Prepare SO management for versionable types #149495

jloleysens commented Jan 25, 2023 •

edited

Loading

jloleysens commented Jan 31, 2023

TinaHeiligers left a comment

TinaHeiligers Feb 2, 2023 •

edited

Loading

TinaHeiligers Feb 2, 2023 •

edited

Loading

TinaHeiligers left a comment

kibana-ci commented Feb 2, 2023

API count

References to deprecated APIs

jloleysens commented Feb 2, 2023

jloleysens commented Feb 2, 2023

[Saved objects] Prepare SO management for versionable types #149495

[Saved objects] Prepare SO management for versionable types #149495

Conversation

jloleysens commented Jan 25, 2023 • edited Loading

Summary

jloleysens commented Jan 31, 2023

TinaHeiligers left a comment

Choose a reason for hiding this comment

TinaHeiligers Feb 2, 2023 • edited Loading

Choose a reason for hiding this comment

TinaHeiligers Feb 2, 2023 • edited Loading

Choose a reason for hiding this comment

TinaHeiligers left a comment

Choose a reason for hiding this comment

kibana-ci commented Feb 2, 2023

💚 Build Succeeded

Metrics [docs]

Module Count

Public APIs missing comments

Async chunks

Public APIs missing exports

Page load bundle

API count

References to deprecated APIs

History

jloleysens commented Feb 2, 2023

jloleysens commented Feb 2, 2023

jloleysens commented Jan 25, 2023 •

edited

Loading

TinaHeiligers Feb 2, 2023 •

edited

Loading

TinaHeiligers Feb 2, 2023 •

edited

Loading