Skip to content

Commit fd630b3

Browse files
kibanamachinelcawl
kibanamachine
and
lcawl
authored
[9.0] [DOCS] Add minimal short URL APIs (#213860) (#214969)
# Backport This will backport the following commits from `main` to `9.0`: - [[DOCS] Add minimal short URL APIs (#213860)](#213860) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Lisa Cawley","email":"[email protected]"},"sourceCommit":{"committedDate":"2025-03-18T12:28:23Z","message":"[DOCS] Add minimal short URL APIs (#213860)","sha":"863a42fd31827e592319fcaf3670a7d18cd3e637","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","docs","Team:SharedUX","backport:version","v9.1.0","v8.19.0","v8.18.1","v9.0.1"],"title":"[DOCS] Add minimal short URL APIs","number":213860,"url":"https://github.com/elastic/kibana/pull/213860","mergeCommit":{"message":"[DOCS] Add minimal short URL APIs (#213860)","sha":"863a42fd31827e592319fcaf3670a7d18cd3e637"}},"sourceBranch":"main","suggestedTargetBranches":["8.x","8.18","9.0"],"targetPullRequestStates":[{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/213860","number":213860,"mergeCommit":{"message":"[DOCS] Add minimal short URL APIs (#213860)","sha":"863a42fd31827e592319fcaf3670a7d18cd3e637"}},{"branch":"8.x","label":"v8.19.0","branchLabelMappingKey":"^v8.19.0$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.18","label":"v8.18.1","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"9.0","label":"v9.0.1","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> Co-authored-by: Lisa Cawley <[email protected]>
1 parent 426bf5c commit fd630b3

File tree

4 files changed

+301
-0
lines changed

4 files changed

+301
-0
lines changed

‎oas_docs/output/kibana.yaml‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,9 @@ tags:
227227
- description: You can create Timelines and Timeline templates via the API, as well as import new Timelines from an ndjson file.
228228
name: Security Timeline API
229229
x-displayName: Security timeline
230+
- description: Manage Kibana short URLs.
231+
name: short url
232+
x-displayName: Short URLs
230233
- description: SLO APIs enable you to define, manage and track service-level objectives
231234
name: slo
232235
x-displayName: Service level objectives
@@ -41660,6 +41663,104 @@ paths:
4166041663
tags:
4166141664
- user session
4166241665
x-state: Technical Preview
41666+
/api/short_url:
41667+
post:
41668+
description: |
41669+
Kibana URLs may be long and cumbersome, short URLs are much easier to remember and share.
41670+
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.
41671+
operationId: post-url
41672+
requestBody:
41673+
content:
41674+
application/json:
41675+
schema:
41676+
type: object
41677+
properties:
41678+
humanReadableSlug:
41679+
description: |
41680+
When the `slug` parameter is omitted, the API will generate a random human-readable slug if `humanReadableSlug` is set to true.
41681+
type: boolean
41682+
locatorId:
41683+
description: The identifier for the locator.
41684+
type: string
41685+
params:
41686+
description: |
41687+
An object which contains all necessary parameters for the given locator to resolve to a Kibana location.
41688+
> warn
41689+
> 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.
41690+
type: object
41691+
slug:
41692+
description: |
41693+
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.
41694+
type: string
41695+
required:
41696+
- locatorId
41697+
- params
41698+
required: true
41699+
responses:
41700+
'200':
41701+
content:
41702+
application/json:
41703+
schema:
41704+
$ref: '#/components/schemas/Short_URL_APIs_urlResponse'
41705+
description: Indicates a successful call.
41706+
summary: Create a short URL
41707+
tags:
41708+
- short url
41709+
x-state: Technical Preview
41710+
/api/short_url/_slug/{slug}:
41711+
get:
41712+
description: |
41713+
Resolve a Kibana short URL by its slug.
41714+
operationId: resolve-url
41715+
parameters:
41716+
- description: The slug of the short URL.
41717+
in: path
41718+
name: slug
41719+
required: true
41720+
schema:
41721+
type: string
41722+
responses:
41723+
'200':
41724+
content:
41725+
application/json:
41726+
schema:
41727+
$ref: '#/components/schemas/Short_URL_APIs_urlResponse'
41728+
description: Indicates a successful call.
41729+
summary: Resolve a short URL
41730+
tags:
41731+
- short url
41732+
x-state: Technical Preview
41733+
/api/short_url/{id}:
41734+
delete:
41735+
description: |
41736+
Delete a Kibana short URL.
41737+
operationId: delete-url
41738+
parameters:
41739+
- $ref: '#/components/parameters/Short_URL_APIs_idParam'
41740+
responses:
41741+
'200':
41742+
description: Indicates a successful call.
41743+
summary: Delete a short URL
41744+
tags:
41745+
- short url
41746+
x-state: Technical Preview
41747+
get:
41748+
description: |
41749+
Get a single Kibana short URL.
41750+
operationId: get-url
41751+
parameters:
41752+
- $ref: '#/components/parameters/Short_URL_APIs_idParam'
41753+
responses:
41754+
'200':
41755+
content:
41756+
application/json:
41757+
schema:
41758+
$ref: '#/components/schemas/Short_URL_APIs_urlResponse'
41759+
description: Indicates a successful call.
41760+
summary: Get a short URL
41761+
tags:
41762+
- short url
41763+
x-state: Technical Preview
4166341764
/api/spaces/_copy_saved_objects:
4166441765
post:
4166541766
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:
4862848729
required: true
4862948730
schema:
4863048731
type: string
48732+
Short_URL_APIs_idParam:
48733+
description: The identifier for the short URL.
48734+
in: path
48735+
name: id
48736+
required: true
48737+
schema:
48738+
type: string
4863148739
SLOs_kbn_xsrf:
4863248740
description: Cross-site request forgery protection
4863348741
in: header
@@ -63069,6 +63177,34 @@ components:
6306963177
- default
6307063178
- template
6307163179
type: string
63180+
Short_URL_APIs_urlResponse:
63181+
type: object
63182+
properties:
63183+
accessCount:
63184+
type: integer
63185+
accessDate:
63186+
type: string
63187+
createDate:
63188+
type: string
63189+
id:
63190+
description: The identifier for the short URL.
63191+
type: string
63192+
locator:
63193+
type: object
63194+
properties:
63195+
id:
63196+
description: The identifier for the locator.
63197+
type: string
63198+
state:
63199+
description: The locator parameters.
63200+
type: object
63201+
version:
63202+
description: The version of Kibana when the short URL was created.
63203+
type: string
63204+
slug:
63205+
description: |
63206+
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.
63207+
type: string
6307263208
SLOs_400_response:
6307363209
title: Bad request
6307463210
type: object

‎oas_docs/scripts/merge_ess_oas.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
2323
`${REPO_ROOT}/src/core/packages/saved-objects/docs/openapi/bundled.yaml`,
2424
`${REPO_ROOT}/x-pack/platform/plugins/private/upgrade_assistant/docs/openapi/upgrade_apis.yaml`,
2525
`${REPO_ROOT}/x-pack/platform/plugins/shared/security/docs/openapi/user_session_apis.yaml`,
26+
`${REPO_ROOT}/src/platform/plugins/shared/share/docs/openapi/short_url_apis.yaml`,
2627
`${REPO_ROOT}/x-pack/platform/plugins/private/logstash/docs/openapi/logstash_apis.yaml`,
2728

2829
// Observability Solution

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# OpenAPI (Experimental)
2+
3+
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.
4+
5+
A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
6+
7+
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‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
openapi: 3.0.3
2+
info:
3+
title: Short URL APIs
4+
description: Kibana APIs for the short URL feature
5+
version: "1.0.1"
6+
license:
7+
name: Elastic License 2.0
8+
url: https://www.elastic.co/licensing/elastic-license
9+
tags:
10+
- name: short url
11+
description: Manage Kibana short URLs.
12+
x-displayName: Short URLs
13+
servers:
14+
- url: /
15+
paths:
16+
/api/short_url:
17+
post:
18+
summary: Create a short URL
19+
description: >
20+
Kibana URLs may be long and cumbersome, short URLs are much easier to remember and share.
21+
22+
Short URLs are created by specifying the locator ID and locator parameters.
23+
When a short URL is resolved, the locator ID and locator parameters are used to redirect user to the right Kibana page.
24+
operationId: post-url
25+
x-state: Technical Preview
26+
tags:
27+
- short url
28+
requestBody:
29+
required: true
30+
content:
31+
application/json:
32+
schema:
33+
type: object
34+
required:
35+
- locatorId
36+
- params
37+
properties:
38+
humanReadableSlug:
39+
type: boolean
40+
description: >
41+
When the `slug` parameter is omitted, the API will generate a random human-readable slug if `humanReadableSlug` is set to true.
42+
locatorId:
43+
type: string
44+
description: The identifier for the locator.
45+
params:
46+
type: object
47+
description: |
48+
An object which contains all necessary parameters for the given locator to resolve to a Kibana location.
49+
> warn
50+
> 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.
51+
slug:
52+
type: string
53+
description: >
54+
A custom short URL slug.
55+
The slug is the part of the short URL that identifies it.
56+
You can provide a custom slug which consists of latin alphabet letters, numbers, and `-._` characters.
57+
The slug must be at least 3 characters long, but no longer than 255 characters.
58+
responses:
59+
'200':
60+
description: Indicates a successful call.
61+
content:
62+
application/json:
63+
schema:
64+
$ref: '#/components/schemas/urlResponse'
65+
/api/short_url/{id}:
66+
delete:
67+
summary: Delete a short URL
68+
description: >
69+
Delete a Kibana short URL.
70+
operationId: delete-url
71+
x-state: Technical Preview
72+
tags:
73+
- short url
74+
parameters:
75+
- $ref: '#/components/parameters/idParam'
76+
responses:
77+
'200':
78+
description: Indicates a successful call.
79+
get:
80+
summary: Get a short URL
81+
description: >
82+
Get a single Kibana short URL.
83+
operationId: get-url
84+
x-state: Technical Preview
85+
tags:
86+
- short url
87+
parameters:
88+
- $ref: '#/components/parameters/idParam'
89+
responses:
90+
'200':
91+
description: Indicates a successful call.
92+
content:
93+
application/json:
94+
schema:
95+
$ref: '#/components/schemas/urlResponse'
96+
/api/short_url/_slug/{slug}:
97+
get:
98+
summary: Resolve a short URL
99+
description: >
100+
Resolve a Kibana short URL by its slug.
101+
operationId: resolve-url
102+
x-state: Technical Preview
103+
tags:
104+
- short url
105+
parameters:
106+
- in: path
107+
name: slug
108+
description: The slug of the short URL.
109+
required: true
110+
schema:
111+
type: string
112+
responses:
113+
'200':
114+
description: Indicates a successful call.
115+
content:
116+
application/json:
117+
schema:
118+
$ref: '#/components/schemas/urlResponse'
119+
components:
120+
parameters:
121+
idParam:
122+
in: path
123+
name: id
124+
description: The identifier for the short URL.
125+
required: true
126+
schema:
127+
type: string
128+
schemas:
129+
urlResponse:
130+
type: object
131+
properties:
132+
accessCount:
133+
type: integer
134+
accessDate:
135+
type: string
136+
createDate:
137+
type: string
138+
id:
139+
type: string
140+
description: The identifier for the short URL.
141+
locator:
142+
type: object
143+
properties:
144+
id:
145+
type: string
146+
description: The identifier for the locator.
147+
state:
148+
type: object
149+
description: The locator parameters.
150+
version:
151+
type: string
152+
description: The version of Kibana when the short URL was created.
153+
slug:
154+
type: string
155+
description: >
156+
A random human-readable slug is automatically generated if the `humanReadableSlug` parameter is set to `true`.
157+
If it is set to `false`, a random short string is generated.

0 commit comments

Comments
 (0)