Skip to content

Commit

Permalink
[8.11] [data views] Swap references API docs (#175183) (#175844)
Browse files Browse the repository at this point in the history 
# Backport

This will backport the following commits from `main` to `8.11`:
- [[data views] Swap references API docs
(#175183)](#175183)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Matthew
Kime","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-01-29T21:04:20Z","message":"[data
views] Swap references API docs (#175183)\n\n## Summary\r\n\r\nDocs for
the swap references api
-\r\nhttps://github.com//pull/163225\r\n\r\nThe docs are
on the terse side - I think this makes sense since this is\r\na tool
that should be used infrequently and only by people who use
saved\r\nobject references.\r\n\r\n---------\r\n\r\nCo-authored-by:
amyjtechwriter
<[email protected]>\r\nCo-authored-by:
Davis McPhee
<[email protected]>","sha":"b371171d86adc0bcd3a331be8526571370916330","branchLabelMapping":{"^v8.13.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:Data
Views","release_note:skip","docs","Team:DataDiscovery","v8.10.0","v8.11.0","v8.12.0","v8.13.0"],"title":"[data
views] Swap references API
docs","number":175183,"url":"https://github.com/elastic/kibana/pull/175183","mergeCommit":{"message":"[data
views] Swap references API docs (#175183)\n\n## Summary\r\n\r\nDocs for
the swap references api
-\r\nhttps://github.com//pull/163225\r\n\r\nThe docs are
on the terse side - I think this makes sense since this is\r\na tool
that should be used infrequently and only by people who use
saved\r\nobject references.\r\n\r\n---------\r\n\r\nCo-authored-by:
amyjtechwriter
<[email protected]>\r\nCo-authored-by:
Davis McPhee
<[email protected]>","sha":"b371171d86adc0bcd3a331be8526571370916330"}},"sourceBranch":"main","suggestedTargetBranches":["8.10","8.11","8.12"],"targetPullRequestStates":[{"branch":"8.10","label":"v8.10.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.11","label":"v8.11.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.12","label":"v8.12.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.13.0","branchLabelMappingKey":"^v8.13.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/175183","number":175183,"mergeCommit":{"message":"[data
views] Swap references API docs (#175183)\n\n## Summary\r\n\r\nDocs for
the swap references api
-\r\nhttps://github.com//pull/163225\r\n\r\nThe docs are
on the terse side - I think this makes sense since this is\r\na tool
that should be used infrequently and only by people who use
saved\r\nobject references.\r\n\r\n---------\r\n\r\nCo-authored-by:
amyjtechwriter
<[email protected]>\r\nCo-authored-by:
Davis McPhee
<[email protected]>","sha":"b371171d86adc0bcd3a331be8526571370916330"}}]}]
BACKPORT-->

Co-authored-by: Matthew Kime <[email protected]>
  • Loading branch information
@kibanamachine @mattkime
kibanamachine and mattkime authored Jan 29, 2024
1 parent 769bed1 commit d3f4e84
Show file tree
Hide file tree
Showing 3 changed files with 162 additions and 0 deletions.
4 changes: 4 additions & 0 deletions docs/api/data-views.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ The following data views APIs are available:
** <<data-views-api-create, Create data view API>> to create data view
** <<data-views-api-update, Update data view API>> to partially updated data view
** <<data-views-api-delete, Delete data view API>> to delete a data view
** <<data-views-api-swap-references-preview, Data view swap references preview API>> to preview a data view reference swap
** <<data-views-api-swap-references, Data view swap references API>> to perform a data view reference swap
* Default data views
** <<data-views-api-default-get, Get default data view API>> to retrieve a default data view
** <<data-views-api-default-set, Set default data view API>> to set a default data view
Expand All @@ -33,6 +35,8 @@ include::data-views/get.asciidoc[]
include::data-views/create.asciidoc[]
include::data-views/update.asciidoc[]
include::data-views/delete.asciidoc[]
include::data-views/swap_references_preview.asciidoc[]
include::data-views/swap_references.asciidoc[]
include::data-views/default-get.asciidoc[]
include::data-views/default-set.asciidoc[]
include::data-views/update-fields.asciidoc[]
Expand Down
84 changes: 84 additions & 0 deletions docs/api/data-views/swap_references.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
[[data-views-api-swap-references]]
=== Swap references data view API
++++
<titleabbrev>Swap references</titleabbrev>
++++

Swap saved object references

[WARNING]
====
Misuse can break large numbers of saved objects! Practicing with a backup is recommended.
====

[NOTE]
====
For the most up-to-date API details, refer to the
{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
====

[[data-views-api-swap-references-request]]
==== Request

`POST <kibana host>:<port>/api/data_views/swap_references`

`POST <kibana host>:<port>/s/<space_id>/api/data_views/swap_references`


[[data-views-api-swap-references-request-body]]
==== Request body

`fromId`::
(Required, string) Saved object reference to change.

`toId`::
(Required, string) New saved object reference value to replace the old.

`delete`::
(Optional, boolean) Deletes referenced saved object if all references are removed.

`fromType`::
(Optional, string) Specify the type of the saved object reference to alter. Default is `index-pattern` for data view.

`forId`::
(Optional, string or string[]) Limit the affected saved objects to one or more by IDs.

`forType`::
(Optional, string) Limit the affected saved objects by type.

[[data-views-api-swap-references-errors-codes]]
==== Response code

`200`::
Indicates a successful call.

[[data-views-api-swap-references-example]]
==== Examples

Swap references to data view id "abcd-efg" with "xyz-123":

[source,sh]
--------------------------------------------------
$ curl -X api/data_views/swap_references
{
"fromId" : "abcd-efg",
"toId" : "xyz-123",
"delete" : true // optional, removes data view which is no longer referenced
}
--------------------------------------------------
// KIBANA

The API returns a list of affected saved objects:

[source,sh]
--------------------------------------------------
{
result: [{ id: "123", type: "visualization" }],
deleteStatus: {
remainingRefs: 0,
deletePerformed: true
}
}
--------------------------------------------------

74 changes: 74 additions & 0 deletions docs/api/data-views/swap_references_preview.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
[[data-views-api-swap-references-preview]]
=== Swap references preview data view API
++++
<titleabbrev>Swap references preview</titleabbrev>
++++

Swap saved object references preview

[NOTE]
====
For the most up-to-date API details, refer to the
{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
====

[[data-views-api-swap-references-preview-request]]
==== Request

`POST <kibana host>:<port>/api/data_views/swap_references/_preview`

`POST <kibana host>:<port>/s/<space_id>/api/data_views/swap_references/_preview`


[[data-views-api-swap-references-preview-request-body]]
==== Request body

`fromId`::
(Required, string) Saved object reference to change.

`toId`::
(Required, string) New saved object reference value to replace the old.

`delete`::
(Optional, boolean) Deletes referenced saved object if all references are removed.

`fromType`::
(Optional, string) Specify the type of the saved object reference to alter. Default is `index-pattern` for data view.

`forId`::
(Optional, string or string[]) Limit the affected saved objects to one or more by IDs.

`forType`::
(Optional, string) Limit the affected saved objects by type.

[[data-views-api-swap-references-preview-errors-codes]]
==== Response code

`200`::
Indicates a successful call.

[[data-views-api-swap-references-preview-example]]
==== Examples

Preview swapping references to data view id "abcd-efg" with "xyz-123":

[source,sh]
--------------------------------------------------
$ curl -X api/data_views/swap_references/_preview
{
"fromId" : "abcd-efg",
"toId" : "xyz-123"
}
--------------------------------------------------
// KIBANA

The API returns a list of affected saved objects:

[source,sh]
--------------------------------------------------
{
result: [{ id: "123", type: "visualization" }],
}
--------------------------------------------------

0 comments on commit d3f4e84

Please sign in to comment.