From d3f4e8498441f27246983d2e5c8173e0bf58ac41 Mon Sep 17 00:00:00 2001
From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Date: Mon, 29 Jan 2024 16:30:22 -0500
Subject: [PATCH] [8.11] [data views] Swap references API docs (#175183)
 (#175844)

# Backport

This will backport the following commits from `main` to `8.11`:
- [[data views] Swap references API docs
(#175183)](https://github.com/elastic/kibana/pull/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":"matt@mattki.me"},"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/elastic/kibana/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
<61687663+amyjtechwriter@users.noreply.github.com>\r\nCo-authored-by:
Davis McPhee
<davismcphee@hotmail.com>","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/elastic/kibana/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
<61687663+amyjtechwriter@users.noreply.github.com>\r\nCo-authored-by:
Davis McPhee
<davismcphee@hotmail.com>","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/elastic/kibana/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
<61687663+amyjtechwriter@users.noreply.github.com>\r\nCo-authored-by:
Davis McPhee
<davismcphee@hotmail.com>","sha":"b371171d86adc0bcd3a331be8526571370916330"}}]}]
BACKPORT-->

Co-authored-by: Matthew Kime <matt@mattki.me>
---
 docs/api/data-views.asciidoc                  |  4 +
 docs/api/data-views/swap_references.asciidoc  | 84 +++++++++++++++++++
 .../swap_references_preview.asciidoc          | 74 ++++++++++++++++
 3 files changed, 162 insertions(+)
 create mode 100644 docs/api/data-views/swap_references.asciidoc
 create mode 100644 docs/api/data-views/swap_references_preview.asciidoc

diff --git a/docs/api/data-views.asciidoc b/docs/api/data-views.asciidoc
index cf9524d4fdf30..ff768fd1a260e 100644
--- a/docs/api/data-views.asciidoc
+++ b/docs/api/data-views.asciidoc
@@ -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
@@ -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[]
diff --git a/docs/api/data-views/swap_references.asciidoc b/docs/api/data-views/swap_references.asciidoc
new file mode 100644
index 0000000000000..26f6f9aada21a
--- /dev/null
+++ b/docs/api/data-views/swap_references.asciidoc
@@ -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
+  }
+}
+--------------------------------------------------
+
diff --git a/docs/api/data-views/swap_references_preview.asciidoc b/docs/api/data-views/swap_references_preview.asciidoc
new file mode 100644
index 0000000000000..16581045aaa35
--- /dev/null
+++ b/docs/api/data-views/swap_references_preview.asciidoc
@@ -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" }],
+}
+--------------------------------------------------
+