Short url docs (#113084)

docs/api/short-urls.asciidoc

@@ -0,0 +1,9 @@
+[[short-urls-api]]
+== Short URLs APIs
+
+Manage {kib} short URLs.
+
+include::short-urls/create-short-url.asciidoc[]
+include::short-urls/get-short-url.asciidoc[]
+include::short-urls/delete-short-url.asciidoc[]
+include::short-urls/resolve-short-url.asciidoc[]

docs/api/short-urls/create-short-url.asciidoc

@@ -0,0 +1,86 @@
+[[short-urls-api-create]]
+=== Create short URL API
+++++
+<titleabbrev>Create short URL</titleabbrev>
+++++
+
+experimental[] Create a {kib} short URL. {kib} URLs may be long and cumbersome, short URLs are much
+easier to remember and share.
+
+Short URLs are created by specifying the locator ID and locator parameters. When a short URL is
+resolved, the locator ID and locator parameters are used to redirect user to the right {kib} page.
+
+
+[[short-urls-api-create-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/short_url`
+
+
+[[short-urls-api-create-request-body]]
+==== Request body
+
+`locatorId`::
+  (Required, string) ID of the locator.
+
+`params`::
+  (Required, object) Object which contains all necessary parameters for the given locator to resolve
+  to a {kib} location.
++
+WARNING: When you create a short URL, locator params are not validated, which allows you to pass
+arbitrary and ill-formed data into the API that can break {kib}. Make sure
+any data that you send to the API is properly formed.
+
+`slug`::
+  (Optional, string) A custom short URL slug. Slug is the part of the short URL that identifies it.
+  You can provide a custom slug which consists of latin alphabet letters, numbers and `-._`
+  characters. The slug must be at least 3 characters long, but no longer than 255 characters.
+
+`humanReadableSlug`::
+  (Optional, boolean) When the `slug` parameter is omitted, the API will generate a random
+  human-readable slug, if `humanReadableSlug` is set to `true`.
+
+
+[[short-urls-api-create-response-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+
+[[short-urls-api-create-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/short_url  -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
+{
+  "locatorId": "LOCATOR_ID",
+  "params": {},
+  "humanReadableSlug": true
+}'
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", <1>
+  "slug": "adjective-adjective-noun", <2>
+  "locator": {
+    "id": "LOCATOR_ID",
+    "version": "x.x.x", <3>
+    "state": {} <4>
+  },
+  "accessCount": 0,
+  "accessDate": 1632680100000,
+  "createDate": 1632680100000
+}
+--------------------------------------------------
+
+<1> A random ID is automatically generated.
+<2> A random human-readable slug is automatically generated if the `humanReadableSlug` parameter is set to `true`. If set to `false` a random short string is generated.
+<3> The version of {kib} when short URL was created is stored.
+<4> Locator params provided as `params` property are stored.

docs/api/short-urls/delete-short-url.asciidoc

@@ -0,0 +1,39 @@
+[[short-urls-api-delete]]
+=== Delete short URL API
+++++
+<titleabbrev>Delete short URL</titleabbrev>
+++++
+
+experimental[] Delete a {kib} short URL.
+
+
+[[short-urls-api-delete-request]]
+==== Request
+
+`DELETE <kibana host>:<port>/api/short_url/<id>`
+
+
+[[short-urls-api-delete-path-params]]
+==== Path parameters
+
+`id`::
+  (Required, string) The short URL ID that you want to remove.
+
+
+[[short-urls-api-delete-response-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+
+[[short-urls-api-delete-example]]
+==== Example
+
+Delete a short URL `12345` ID:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X DELETE api/short_url/12345
+--------------------------------------------------
+// KIBANA

docs/api/short-urls/get-short-url.asciidoc

@@ -0,0 +1,56 @@
+[[short-urls-api-get]]
+=== Get short URL API
+++++
+<titleabbrev>Get short URL</titleabbrev>
+++++
+
+experimental[] Retrieve a single {kib} short URL.
+
+[[short-urls-api-get-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/short_url/<id>`
+
+
+[[short-urls-api-get-params]]
+==== Path parameters
+
+`id`::
+  (Required, string) The ID of the short URL.
+
+
+[[short-urls-api-get-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+
+[[short-urls-api-get-example]]
+==== Example
+
+Retrieve the short URL with the `12345` ID:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/short_url/12345
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "id": "12345",
+  "slug": "adjective-adjective-noun",
+  "locator": {
+    "id": "LOCATOR_ID",
+    "version": "x.x.x",
+    "state": {}
+  },
+  "accessCount": 0,
+  "accessDate": 1632680100000,
+  "createDate": 1632680100000
+}
+--------------------------------------------------

docs/api/short-urls/resolve-short-url.asciidoc

@@ -0,0 +1,56 @@
+[[short-urls-api-resolve]]
+=== Resolve short URL API
+++++
+<titleabbrev>Resolve short URL</titleabbrev>
+++++
+
+experimental[] Resolve a single {kib} short URL by its slug.
+
+[[short-urls-api-resolve-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/short_url/_slug/<slug>`
+
+
+[[short-urls-api-resolve-params]]
+==== Path parameters
+
+`slug`::
+  (Required, string) The slug of the short URL.
+
+
+[[short-urls-api-resolve-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+
+[[short-urls-api-resolve-example]]
+==== Example
+
+Retrieve the short URL with the `hello-world` ID:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/short_url/_slug/hello-world
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "id": "12345",
+  "slug": "hello-world",
+  "locator": {
+    "id": "LOCATOR_ID",
+    "version": "x.x.x",
+    "state": {}
+  },
+  "accessCount": 0,
+  "accessDate": 1632680100000,
+  "createDate": 1632680100000
+}
+--------------------------------------------------

docs/api/url-shortening.asciidoc

@@ -1,62 +0,0 @@
-[[url-shortening-api]]
-== Shorten URL API
-++++
-<titleabbrev>Shorten URL</titleabbrev>
-++++
-
-experimental[] Convert a {kib} URL into a token. {kib} URLs contain the state of the application, which makes them long and cumbersome.
-Internet Explorer has URL length restrictions, and some wiki and markup parsers don't do well with the full-length version of the {kib} URL.
-
-Short URLs are designed to make sharing {kib} URLs easier.
-
-[float]
-[[url-shortening-api-request]]
-=== Request
-
-`POST <kibana host>:<port>/api/shorten_url`
-
-[float]
-[[url-shortening-api-request-body]]
-=== Request body
-
-`url`::
-  (Required, string) The {kib} URL that you want to shorten, relative to `/app/kibana`.
-
-[float]
-[[url-shortening-api-response-body]]
-=== Response body
-
-urlId:: A top-level property that contains the shortened URL token for the provided request body.
-
-[float]
-[[url-shortening-api-codes]]
-=== Response code
-
-`200`::
-  Indicates a successful call.
-
-[float]
-[[url-shortening-api-example]]
-=== Example
-
-[source,sh]
---------------------------------------------------
-$ curl -X POST api/shorten_url
-{
-  "url": "/app/kibana#/dashboard?_g=()&_a=(description:'',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),panels:!((embeddableConfig:(),gridData:(h:15,i:'1',w:24,x:0,y:0),id:'8f4d0c00-4c86-11e8-b3d7-01146121b73d',panelIndex:'1',type:visualization,version:'7.0.0-alpha1')),query:(language:lucene,query:''),timeRestore:!f,title:'New%20Dashboard',viewMode:edit)"
-}
---------------------------------------------------
-// KIBANA
-
-The API returns the following:
-
-[source,sh]
---------------------------------------------------
-{
-  "urlId": "f73b295ff92718b26bc94edac766d8e3"
-}
---------------------------------------------------
-
-For easy sharing, construct the shortened {kib} URL:
-
-`http://localhost:5601/goto/f73b295ff92718b26bc94edac766d8e3`

docs/user/api.asciidoc

@@ -1,8 +1,8 @@
 [[api]]
 = REST API
 
-Some {kib} features are provided via a REST API, which is ideal for creating an 
-integration with {kib}, or automating certain aspects of configuring and 
+Some {kib} features are provided via a REST API, which is ideal for creating an
+integration with {kib}, or automating certain aspects of configuring and
 deploying {kib}.
 
 [float]
@@ -18,15 +18,15 @@ NOTE: The {kib} Console supports only Elasticsearch APIs. You are unable to inte
 [float]
 [[api-authentication]]
 === Authentication
-The {kib} APIs support key- and token-based authentication. 
+The {kib} APIs support key- and token-based authentication.
 
 [float]
 [[token-api-authentication]]
 ==== Token-based authentication
 
-To use token-based authentication, you use the same username and password that you use to log into Elastic.  
-In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option, 
-which is where the username and password are stored in order to be passed as part of the call. 
+To use token-based authentication, you use the same username and password that you use to log into Elastic.
+In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option,
+which is where the username and password are stored in order to be passed as part of the call.
 
 [float]
 [[key-authentication]]
@@ -65,7 +65,7 @@ For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsr
 * XSRF protections are disabled using the <<settings-xsrf-disableProtection, `server.xsrf.disableProtection`>> setting
 
 `Content-Type: application/json`::
-  Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. 
+  Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON.
   Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
 
 Request header example:
@@ -97,6 +97,6 @@ include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[]
 include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
 include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
 include::{kib-repo-dir}/api/machine-learning.asciidoc[]
-include::{kib-repo-dir}/api/url-shortening.asciidoc[]
+include::{kib-repo-dir}/api/short-urls.asciidoc[]
 include::{kib-repo-dir}/api/task-manager/health.asciidoc[]
 include::{kib-repo-dir}/api/upgrade-assistant.asciidoc[]