[8.5] Document update objects spaces API (#145109) (#145280)

# Backport This will backport the following commits from `main` to `8.5`: - [Document update objects spaces API (#145109)](#145109)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Thom Heymann <[email protected]>
elastic · Nov 15, 2022 · 382984f · 382984f
1 parent b7886ae
commit 382984f
Show file tree

Hide file tree

Showing 3 changed files with 229 additions and 0 deletions.
diff --git a/docs/api/spaces-management.asciidoc b/docs/api/spaces-management.asciidoc
@@ -22,6 +22,10 @@ The following {kib} spaces APIs are available:
 
 * <<spaces-api-disable-legacy-url-aliases, Disable legacy URL aliases API>> to disable legacy URL aliases if an error is encountered
 
+* <<spaces-api-update-objects-spaces, Update saved objects spaces API>> to update one or more saved objects to add and/or remove them from specified spaces
+
+* <<spaces-api-get-shareable-references, Get shareable references API>> to collect references and spaces context for saved objects
+
 include::spaces-management/post.asciidoc[]
 include::spaces-management/put.asciidoc[]
 include::spaces-management/get.asciidoc[]
@@ -30,3 +34,5 @@ include::spaces-management/delete.asciidoc[]
 include::spaces-management/copy_saved_objects.asciidoc[]
 include::spaces-management/resolve_copy_saved_objects_conflicts.asciidoc[]
 include::spaces-management/disable_legacy_url_aliases.asciidoc[]
+include::spaces-management/update_objects_spaces.asciidoc[]
+include::spaces-management/get_shareable_references.asciidoc[]
diff --git a/docs/api/spaces-management/get_shareable_references.asciidoc b/docs/api/spaces-management/get_shareable_references.asciidoc
@@ -0,0 +1,81 @@
+[role="xpack"]
+[[spaces-api-get-shareable-references]]
+=== Get shareable references API
+++++
+<titleabbrev>Get shareable references</titleabbrev>
+++++
+
+experimental[] Get shareable references.
+
+Collects references and spaces context for saved objects.
+
+[[spaces-api-get-shareable-references-request]]
+==== {api-request-title}
+
+`POST <kibana host>:<port>/api/spaces/_get_shareable_references`
+
+[[spaces-api-get-shareable-references-request-body]]
+==== {api-request-body-title}
+
+`objects`::
+  (Required, object array) The saved objects to collect outbound references for.
++
+.Properties of `objects`
+[%collapsible%open]
+=====
+  `type`:::
+    (Required, string) The saved object type.
+
+  `id`:::
+    (Required, string) The saved object ID.
+=====
+
+[role="child_attributes"]
+[[spaces-api-get-shareable-references-response-body]]
+==== {api-response-body-title}
+
+`objects`::
+  (object array) The returned input object or one of its references, with additional context.
++
+.Properties of `objects`
+[%collapsible%open]
+=====
+  `type`:::
+    (string) The saved object type.
+
+  `id`:::
+    (string) The saved object ID.
+
+  `originId`:::
+    (string) The origin ID of the referenced object (if it has one).
+
+  `inboundReferences`:::
+    (object array) References to this object.
++
+NOTE: This does not contain _all inbound references everywhere_, it only contains inbound references to this object within the scope of this operation.
++
+.Properties of `inboundReferences`
+[%collapsible%open]
+======
+    `type`::::
+      (string) The type of the object that has the inbound reference.
+
+    `id`::::
+      (string) The ID of the object that has the inbound reference.
+
+    `name`::::
+      (string) The name of the inbound reference.
+======
+
+  `spaces`:::
+    (string array) The space(s) that the referenced saved object exists in.
+
+  `spacesWithMatchingAliases`:::
+    (string array) The space(s) that legacy URL aliases matching this type/id exist in. (if there are any)
+
+  `spacesWithMatchingOrigins`:::
+    (string array) The space(s) that objects matching this origin exist in (including this one). (if there are any)
+
+  `isMissing`:::
+    (boolean) Whether or not this object or reference is missing.
+=====
diff --git a/docs/api/spaces-management/update_objects_spaces.asciidoc b/docs/api/spaces-management/update_objects_spaces.asciidoc
@@ -0,0 +1,142 @@
+[role="xpack"]
+[[spaces-api-update-objects-spaces]]
+=== Update saved objects spaces API
+++++
+<titleabbrev>Update saved objects spaces</titleabbrev>
+++++
+
+experimental[] Update saved objects spaces.
+
+Updates one or more saved objects to add and/or remove them from specified spaces.
+
+[[spaces-api-update-objects-spaces-request]]
+==== {api-request-title}
+
+`POST <kibana host>:<port>/api/spaces/_update_objects_spaces`
+
+[[spaces-api-update-objects-spaces-request-body]]
+==== {api-request-body-title}
+
+`objects`::
+  (Required, object array) The saved objects to update.
++
+.Properties of `objects`
+[%collapsible%open]
+=====
+  `type`:::
+    (Required, string) The saved object type.
+
+  `id`:::
+    (Required, string) The saved object ID.
+=====
+
+`spacesToAdd`::
+  (Required, string array) The IDs of the spaces the specified objects should be added to.
+
+`spacesToRemove`::
+  (Required, string array) The IDs of the spaces the specified objects should be removed from.
+
+[role="child_attributes"]
+[[spaces-api-update-objects-spaces-response-body]]
+==== {api-response-body-title}
+
+`objects`::
+  (object array) The saved objects that have been updated.
++
+.Properties of `objects`
+[%collapsible%open]
+=====
+  `type`:::
+    (string) The saved object type.
+
+  `id`:::
+    (string) The saved object ID.
+
+  `spaces`:::
+    (string array) The space(s) that the referenced saved object exists in.
+
+  `errors`:::
+    (string) Included if there was an error updating this object's spaces.
+=====
+
+[[spaces-api-update-objects-spaces-example]]
+==== {api-examples-title}
+
+[[spaces-api-update-objects-spaces-example-1]]
+===== Sharing saved objects
+
+To share a saved object to a space programmatically follow these steps:
+
+1. Collect reference graph and spaces context for each saved object that you want to share using <<spaces-api-get-shareable-references, Get shareable references API>>:
++
+[source,sh]
+----
+$ curl -X POST /api/spaces/_get_shareable_references
+{
+  "objects": [
+    {
+      "type": "index-pattern",
+      "id": "90943e30-9a47-11e8-b64d-95841ca0b247"
+    }
+  ]
+}
+----
++
+The API returns the following:
++
+[source,json]
+----
+{
+  "objects": [
+    {
+      "type": "index-pattern",
+      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
+      "spaces": ["default"],
+      "inboundReferences": [],
+      "spacesWithMatchingOrigins": ["default"]
+    }
+  ]
+}
+----
+
+2. Check each saved object for `spacesWithMatchingOrigins` conflicts.
++
+Objects should not be shared to spaces with matching origins or you will create URL conflicts (causing the same URL to point to different saved objects).
+
+3. Check each saved object for `spacesWithMatchingAliases` conflicts.
++
+If these match the space(s) that these saved objects will be shared to you should disable legacy URL aliases for them using <<spaces-api-disable-legacy-url-aliases, Disable legacy URL aliases API>>.
++
+When sharing to all spaces (`*`) all entries in `spacesWithMatchingAliases` should be checked.
+
+4. Update spaces of each saved object and all its references:
++
+[source,sh]
+----
+$ curl -X POST /api/spaces/_update_objects_spaces
+{
+  "objects": [
+    {
+      "type": "index-pattern",
+      "id": "90943e30-9a47-11e8-b64d-95841ca0b247"
+    }
+  ],
+  "spacesToAdd": ["test"],
+  "spacesToRemove": []
+}
+----
++
+The API returns the following:
++
+[source,json]
+----
+{
+  "objects": [
+    {
+      "type": "index-pattern",
+      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
+      "spaces": ["default", "test"]
+    }
+  ]
+}
+----