[9.0] [DOCS] Add minimal short URL APIs (#213860)

oas_docs/output/kibana.yaml

@@ -227,6 +227,9 @@ tags:
   - description: You can create Timelines and Timeline templates via the API, as well as import new Timelines from an ndjson file.
     name: Security Timeline API
     x-displayName: Security timeline
+  - description: Manage Kibana short URLs.
+    name: short url
+    x-displayName: Short URLs
   - description: SLO APIs enable you to define, manage and track service-level objectives
     name: slo
     x-displayName: Service level objectives
@@ -41660,6 +41663,104 @@ paths:
       tags:
         - user session
       x-state: Technical Preview
+  /api/short_url:
+    post:
+      description: |
+        Kibana 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 Kibana page.
+      operationId: post-url
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                humanReadableSlug:
+                  description: |
+                    When the `slug` parameter is omitted, the API will generate a random human-readable slug if `humanReadableSlug` is set to true.
+                  type: boolean
+                locatorId:
+                  description: The identifier for the locator.
+                  type: string
+                params:
+                  description: |
+                    An object which contains all necessary parameters for the given locator to resolve to a Kibana location.
+                    > warn
+                    > 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 Kibana. Make sure any data that you send to the API is properly formed.
+                  type: object
+                slug:
+                  description: |
+                    A custom short URL slug. The 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.
+                  type: string
+              required:
+                - locatorId
+                - params
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Short_URL_APIs_urlResponse'
+          description: Indicates a successful call.
+      summary: Create a short URL
+      tags:
+        - short url
+      x-state: Technical Preview
+  /api/short_url/_slug/{slug}:
+    get:
+      description: |
+        Resolve a Kibana short URL by its slug.
+      operationId: resolve-url
+      parameters:
+        - description: The slug of the short URL.
+          in: path
+          name: slug
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Short_URL_APIs_urlResponse'
+          description: Indicates a successful call.
+      summary: Resolve a short URL
+      tags:
+        - short url
+      x-state: Technical Preview
+  /api/short_url/{id}:
+    delete:
+      description: |
+        Delete a Kibana short URL.
+      operationId: delete-url
+      parameters:
+        - $ref: '#/components/parameters/Short_URL_APIs_idParam'
+      responses:
+        '200':
+          description: Indicates a successful call.
+      summary: Delete a short URL
+      tags:
+        - short url
+      x-state: Technical Preview
+    get:
+      description: |
+        Get a single Kibana short URL.
+      operationId: get-url
+      parameters:
+        - $ref: '#/components/parameters/Short_URL_APIs_idParam'
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Short_URL_APIs_urlResponse'
+          description: Indicates a successful call.
+      summary: Get a short URL
+      tags:
+        - short url
+      x-state: Technical Preview
   /api/spaces/_copy_saved_objects:
     post:
       description: 'It also allows you to automatically copy related objects, so when you copy a dashboard, this can automatically copy over the associated visualizations, data views, and saved Discover sessions, as required. You can request to overwrite any objects that already exist in the target space if they share an identifier or you can use the resolve copy saved objects conflicts API to do this on a per-object basis.<br/><br/>[Required authorization] Route required privileges: ALL of [copySavedObjectsToSpaces].'
@@ -48628,6 +48729,13 @@ components:
       required: true
       schema:
         type: string
+    Short_URL_APIs_idParam:
+      description: The identifier for the short URL.
+      in: path
+      name: id
+      required: true
+      schema:
+        type: string
     SLOs_kbn_xsrf:
       description: Cross-site request forgery protection
       in: header
@@ -63069,6 +63177,34 @@ components:
         - default
         - template
       type: string
+    Short_URL_APIs_urlResponse:
+      type: object
+      properties:
+        accessCount:
+          type: integer
+        accessDate:
+          type: string
+        createDate:
+          type: string
+        id:
+          description: The identifier for the short URL.
+          type: string
+        locator:
+          type: object
+          properties:
+            id:
+              description: The identifier for the locator.
+              type: string
+            state:
+              description: The locator parameters.
+              type: object
+            version:
+              description: The version of Kibana when the short URL was created.
+              type: string
+        slug:
+          description: |
+            A random human-readable slug is automatically generated if the `humanReadableSlug` parameter is set to `true`. If it is set to `false`, a random short string is generated.
+          type: string
     SLOs_400_response:
       title: Bad request
       type: object

oas_docs/scripts/merge_ess_oas.js

@@ -23,6 +23,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/src/core/packages/saved-objects/docs/openapi/bundled.yaml`,
       `${REPO_ROOT}/x-pack/platform/plugins/private/upgrade_assistant/docs/openapi/upgrade_apis.yaml`,
       `${REPO_ROOT}/x-pack/platform/plugins/shared/security/docs/openapi/user_session_apis.yaml`,
+      `${REPO_ROOT}/src/platform/plugins/shared/share/docs/openapi/short_url_apis.yaml`,
       `${REPO_ROOT}/x-pack/platform/plugins/private/logstash/docs/openapi/logstash_apis.yaml`,
 
       // Observability Solution

src/platform/plugins/shared/share/docs/openapi/README.md

@@ -0,0 +1,7 @@
+# OpenAPI (Experimental)
+
+The current self-contained spec file can be used for online tools like those found at https://openapi.tools/. This spec is experimental and may be incomplete or change later.
+
+A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
+
+These files are joined with the rest of the Kibana APIs per `oas_docs/README.md`

src/platform/plugins/shared/share/docs/openapi/short_url_apis.yaml

@@ -0,0 +1,157 @@
+openapi: 3.0.3
+info:
+  title: Short URL APIs
+  description: Kibana APIs for the short URL feature
+  version: "1.0.1"
+  license:
+    name: Elastic License 2.0
+    url: https://www.elastic.co/licensing/elastic-license
+tags:
+  - name: short url
+    description: Manage Kibana short URLs.
+    x-displayName: Short URLs
+servers:
+  - url: /
+paths:
+  /api/short_url:
+    post:
+      summary: Create a short URL
+      description: >
+        Kibana 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 Kibana page.
+      operationId: post-url
+      x-state: Technical Preview
+      tags:
+        - short url
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - locatorId
+                - params
+              properties:
+                humanReadableSlug:
+                  type: boolean
+                  description: >
+                    When the `slug` parameter is omitted, the API will generate a random human-readable slug if `humanReadableSlug` is set to true.
+                locatorId:
+                  type: string
+                  description: The identifier for the locator.
+                params:
+                  type: object
+                  description: |
+                    An object which contains all necessary parameters for the given locator to resolve to a Kibana location.
+                    > warn
+                    > 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 Kibana. Make sure any data that you send to the API is properly formed.
+                slug:
+                  type: string
+                  description: >
+                    A custom short URL slug.
+                    The 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.
+      responses:
+        '200':
+          description: Indicates a successful call.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/urlResponse'
+  /api/short_url/{id}:
+    delete:
+      summary: Delete a short URL
+      description: >
+        Delete a Kibana short URL.
+      operationId: delete-url
+      x-state: Technical Preview
+      tags:
+        - short url
+      parameters:
+        - $ref: '#/components/parameters/idParam'
+      responses:
+        '200':
+          description: Indicates a successful call.
+    get:
+      summary: Get a short URL
+      description: >
+        Get a single Kibana short URL.
+      operationId: get-url
+      x-state: Technical Preview
+      tags:
+        - short url
+      parameters:
+        - $ref: '#/components/parameters/idParam'
+      responses:
+        '200':
+          description: Indicates a successful call.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/urlResponse'
+  /api/short_url/_slug/{slug}:
+    get:
+      summary: Resolve a short URL
+      description: >
+        Resolve a Kibana short URL by its slug.
+      operationId: resolve-url
+      x-state: Technical Preview
+      tags:
+        - short url
+      parameters:
+        - in: path
+          name: slug
+          description: The slug of the short URL.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Indicates a successful call.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/urlResponse'
+components:
+  parameters:
+    idParam:
+      in: path
+      name: id
+      description: The identifier for the short URL.
+      required: true
+      schema:
+        type: string
+  schemas:
+    urlResponse:
+      type: object
+      properties:
+        accessCount:
+          type: integer
+        accessDate:
+          type: string
+        createDate:
+          type: string
+        id:
+          type: string
+          description: The identifier for the short URL.
+        locator:
+          type: object
+          properties:
+            id:
+              type: string
+              description: The identifier for the locator.
+            state:
+              type: object
+              description: The locator parameters.
+            version:
+              type: string
+              description: The version of Kibana when the short URL was created.
+        slug:
+          type: string
+          description: >
+            A random human-readable slug is automatically generated if the `humanReadableSlug` parameter is set to `true`.
+            If it is set to `false`, a random short string is generated.