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
+
 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]]
+==== Request
+
+`POST <kibana host>:<port>/api/spaces/_disable_legacy_url_aliases`
+
+[[spaces-api-disable-legacy-url-aliases-request-body]]
+==== Request body
+
+`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]]
+==== Response codes
+
+`204`::
+  Indicates a successful call.
+
+[[spaces-api-disable-legacy-url-aliases-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/spaces/_disable_legacy_url_aliases
+{
+  "aliases": [
+    {
+      "targetSpace": "bills-space",
+      "targetType": "dashboard",
+      "sourceId": "123"
+    }
+  ]
+}
+--------------------------------------------------
+// KIBANA
+
+This will leave the alias intact, but the legacy URL for this alias will no longer function. In this example, you had a legacy URL for
+`http://localhost:5601/s/bills-space/app/dashboards#/view/123`. That URL would no longer work after making this API call, but the dashboard
+itself still exists and can be accessed by its 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 are being converted in the 8.0 release of {kib} 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*.
+
+When a saved object is converted, if its ID is changed, {kib} creates a special entity called a _legacy URL alias_. This allows us to
+preserve any deep link URLs that may exist for that object.
+
+[[legacy-url-aliases-example]]
+=== Example
+
+For example, consider the following scenario:
+
+You have {kib} 7.16 installed and you created a new dashboard. This dashboard's ID is "123". Then, you create a new space called "Bill's space", and 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 use your web browser to add bookmarks for them. After some time, you decide 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". Now, 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 it finds the new
+object ID. This means if you navigate to `http://localhost:5601/s/bills-space/app/dashboards#/view/123`, you'll see a helpful toast message
+indicating that the dashboard has a new URL, and you'll automatically get 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 some very rare situations where this can lead to an error. For
+example, you may have a dashboard and one of the visualizations may fail 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 by disabling the alias -- you just won't be able to use the old URL to access that saved object anymore.
+
+To disable a legacy URL alias, you'll need three pieces of information about it: the `targetSpace`, the `targetType`, and the `sourceId`.
+Once you have this information, you can use the <<spaces-api-disable-legacy-url-aliases,`_disable_legacy_url_aliases`>> API to disable the
+problematic legacy URL alias.