Add docs for legacy URL aliases

docs/api/spaces-management.asciidoc

@@ -20,10 +20,13 @@ The following {kib} spaces APIs are available:
 
 * <<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects to space conflicts API>> to overwrite saved objects returned as errors from the copy saved objects to space API
 
+* <<spaces-api-disable-legacy-url-aliases, Disable legacy URL aliases API>> to disable legacy URL aliases if an error is encountered
+
 include::spaces-management/post.asciidoc[]
 include::spaces-management/put.asciidoc[]
 include::spaces-management/get.asciidoc[]
 include::spaces-management/get_all.asciidoc[]
 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[]

docs/api/spaces-management/disable_legacy_url_aliases.asciidoc

@@ -0,0 +1,59 @@
+[[spaces-api-disable-legacy-url-aliases]]
+=== Disable legacy URL aliases API
+++++
+<titleabbrev>Disable legacy URL aliases</titleabbrev>
+++++
+
+experimental[] Disable a <<legacy-url-aliases,legacy URL alias>> in {kib}.
+
+[[spaces-api-disable-legacy-url-aliases-request]]
+==== {api-request-title}
+
+`POST <kibana host>:<port>/api/spaces/_disable_legacy_url_aliases`
+
+[role="child_attributes"]
+[[spaces-api-disable-legacy-url-aliases-request-body]]
+==== {api-request-body-title}
+
+`aliases`::
+  (Required, object array) The aliases to disable.
++
+.Properties of `aliases`
+[%collapsible%open]
+=====
+  `targetSpace`:::
+    (Required, string) The space where the alias target object exists.
+
+  `targetType`:::
+    (Required, string) The type of the alias target object.
+
+  `sourceId`:::
+    (Required, string) The ID of the alias source object. This is the "legacy" object ID.
+=====
+
+[[spaces-api-disable-legacy-url-aliases-response-codes]]
+==== {api-response-codes-title}
+
+`204`::
+  Indicates a successful call.
+
+[[spaces-api-disable-legacy-url-aliases-example]]
+==== {api-examples-title}
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/spaces/_disable_legacy_url_aliases
+{
+  "aliases": [
+    {
+      "targetSpace": "bills-space",
+      "targetType": "dashboard",
+      "sourceId": "123"
+    }
+  ]
+}
+--------------------------------------------------
+// KIBANA
+
+This example leaves the alias intact, but the legacy URL for this alias, http://localhost:5601/s/bills-space/app/dashboards#/view/123, will
+no longer function. The dashboard still exists, and you can access it with the new URL.

docs/developer/advanced/index.asciidoc

@@ -6,6 +6,7 @@
 * <<development-basepath>>
 * <<upgrading-nodejs>>
 * <<sharing-saved-objects>>
+* <<legacy-url-aliases>>
 
 include::development-es-snapshots.asciidoc[leveloffset=+1]
 
@@ -15,4 +16,6 @@ include::development-basepath.asciidoc[leveloffset=+1]
 
 include::upgrading-nodejs.asciidoc[leveloffset=+1]
 
-include::sharing-saved-objects.asciidoc[leveloffset=+1]
+include::sharing-saved-objects.asciidoc[leveloffset=+1]
+
+include::legacy-url-aliases.asciidoc[leveloffset=+1]

docs/developer/advanced/legacy-url-aliases.asciidoc

@@ -0,0 +1,45 @@
+[[legacy-url-aliases]]
+== Legacy URL Aliases
+
+This page describes legacy URL aliases: what they are, where they come from, and how to disable them.
+
+[[legacy-url-aliases-overview]]
+=== Overview
+
+Many saved object types were converted in {kib} 8.0, so they can eventually be shared across <<xpack-spaces,spaces>>. Before 8.0, you could
+have two objects with the same type and same ID in two different spaces. Part of this conversion is to make sure all object IDs of a given
+type are *globally unique across all spaces*.
+
+{kib} creates a special entity called a **legacy URL alias** for each saved object that requires a new ID. This legacy URL alias allows
+{kib} to preserve any deep link URLs that exist for these objects.
+
+[[legacy-url-aliases-example]]
+=== Example
+
+Consider the following scenario:
+
+You have {kib} 7.16, and you create a new dashboard.The ID of this dashboard is "123". You create a new space called "Bill's space" and
+<<managing-saved-objects-copy-to-space,copy>> your dashboard to the other space. Now you have two different dashboards that can be accessed
+at the following URLs:
+
+* *Default space*: `http://localhost:5601/app/dashboards#/view/123`
+* *Bill's space*: `http://localhost:5601/s/bills-space/app/dashboards#/view/123`
+
+You use these two dashboards frequently, so you bookmark them in your web browser. After some time, you decide to upgrade to {kib} 8.0. When
+these two dashboards go through the conversion process, the one in "Bill's space" will have its ID changed to "456". The URL to access that
+dashboard is different -- not to worry though, there is a legacy URL alias for that dashboard.
+
+If you use your bookmark to access that dashboard using its old URL, {kib} detects that you are using a legacy URL, and finds the new object
+ID. If you navigate to `http://localhost:5601/s/bills-space/app/dashboards#/view/123`, you'll see a message indicating that the dashboard
+has a new URL, and you're automatically redirected to `http://localhost:5601/s/bills-space/app/dashboards#/view/456`.
+
+[[legacy-url-aliases-handling-errors]]
+=== Handling errors
+
+Legacy URL aliases are intended to be fully transparent, but there are rare situations where this can lead to an error. For example, you
+might have a dashboard and one of the visualizations fails to load, directing you to this page. If you encounter an error in this situation,
+you might want to disable the legacy URL alias completely. This leaves the saved object intact, and you will not lose any data -- you just
+won't be able to use the old URL to access that saved object.
+
+To disable a legacy URL alias, you need three pieces of information: the `targetSpace`, the `targetType`, and the `sourceId`. Then use the
+<<spaces-api-disable-legacy-url-aliases,`_disable_legacy_url_aliases`>> API to disable the problematic legacy URL alias.