[8.2] Document update objects spaces API (#145109) (#145277)

# Backport This will backport the following commits from `main` to `8.2`: - [Document update objects spaces API (#145109)](https://github.com/elastic/kibana/pull/145109)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Thom Heymann <190132+thomheymann@users.noreply.github.com>
2025-04-24 01:38:56 -04:00 · 2022-11-15 12:21:05 -05:00 · 2022-11-15 12:21:05 -05:00 · c00404a0bd
commit c00404a0bd
parent 6f9143eec5
3 changed files with 229 additions and 0 deletions
--- 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[]
--- 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.
+=====
--- 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"]
+    }
+  ]
+}
+----