[Docs] Add details to SO APIs landing page (#191693)

Fix #191534 The deprecation warning in the Kibana Saved Objects API main page was removed in #190654. This PR adds a section about when the APIs will be removed and what to use instead. The PR also includes updates to other API main pages that mention the SO APIs. - [x] [Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html) was added for features that require explanation or tutorials VIew the [html diff](https://kibana_bk_191693.docs-preview.app.elstc.co/diff) for these changes: ![Short URLs API landing page](https://github.com/user-attachments/assets/3716f33e-0d00-4ff7-b29d-7a5ba0a0f1f2) ![Data views API landing page](https://github.com/user-attachments/assets/81c8a843-27ca-4510-a181-7ec9b20f86d6) The updated OpenAPI document looks like this in a Bump.sh preview: ![image](https://github.com/user-attachments/assets/a8b58142-5082-4b75-8b3f-339b8a6b57e4) --------- Co-authored-by: lcawl <[email protected]>
elastic · Aug 29, 2024 · dd221a7 · dd221a7
1 parent 6826eaf
commit dd221a7
Show file tree

Hide file tree

Showing 15 changed files with 101 additions and 32 deletions.
diff --git a/docs/api/dashboard-api.asciidoc b/docs/api/dashboard-api.asciidoc
@@ -1,7 +1,7 @@
 [[dashboard-api]]
 == Import and export dashboard APIs
 
-deprecated::[7.15.0,Both of these APIs have been deprecated in favor of the {api-kibana}/group/endpoint-saved-objects[saved objects API].]
+deprecated::[7.15.0,Both of these APIs have been deprecated and will be removed in 9.0.0]
 
 Import and export dashboards with the corresponding saved objects, such as visualizations, saved
 searches, and data views.
@@ -16,4 +16,4 @@ The following import and export dashboard APIs are available:
 * <<dashboard-api-export, Export dashboard API>> to export dashboards and corresponding saved objects
 
 include::dashboard/import-dashboard.asciidoc[]
-include::dashboard/export-dashboard.asciidoc[]
+include::dashboard/export-dashboard.asciidoc[]
diff --git a/docs/api/data-views.asciidoc b/docs/api/data-views.asciidoc
@@ -8,5 +8,3 @@ For the latest details, refer to {api-kibana}/group/endpoint-data-views[data vie
 WARNING: Do not write documents directly to the `.kibana` index. When you write directly
 to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
 
-WARNING: Use the data views APIs for managing data views instead of lower-level <<saved-objects-api, saved objects API>>.
-
diff --git a/docs/api/osquery-manager.asciidoc b/docs/api/osquery-manager.asciidoc
@@ -3,7 +3,7 @@
 
 experimental[] Run live queries, manage packs and saved queries
 
-WARNING: Use the osquery manager APIs for managing packs and saved queries instead of lower-level <<saved-objects-api, saved objects API>>.
+Use the osquery manager APIs for managing packs and saved queries.
 
 The following osquery manager APIs are available: 
 

diff --git a/docs/api/saved-objects.asciidoc b/docs/api/saved-objects.asciidoc
@@ -1,9 +1,4 @@
 [[saved-objects-api]]
 == Saved objects APIs
 
-Manage {kib} saved objects, including dashboards, visualizations, and more.
-
-For the latest details, refer to the {api-kibana}/group/endpoint-saved-objects[saved object API].
-
-WARNING: Do not write documents directly to the `.kibana` index. When you write directly
-to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
+For the latest details, refer to the {api-kibana}/group/endpoint-saved-objects[saved objects API].
diff --git a/docs/api/short-urls.asciidoc b/docs/api/short-urls.asciidoc
@@ -1,7 +1,14 @@
 [[short-urls-api]]
 == Short URLs APIs
 
-Manage {kib} short URLs.
+experimental[] Manage {kib} short URLs.
+
+The following short urls APIs are available:
+
+* <<short-urls-api-create, Create short URL API>>
+* <<short-urls-api-get, Get short URL API>>
+* <<short-urls-api-delete, Delete short URL API>>
+* <<short-urls-api-resolve, Resolve short URL API>>
 
 include::short-urls/create-short-url.asciidoc[]
 include::short-urls/get-short-url.asciidoc[]

diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
@@ -19031,10 +19031,25 @@ tags:
   - name: Fleet uninstall tokens
   - description: Machine learning
     name: ml
-  - description: >-
-      Manage Kibana saved objects, including dashboards, visualizations, and
-      more.
+  - description: >
+      Export sets of saved objects that you want to import into {kib}, resolve
+      import errors, and rotate an encryption key for encrypted saved objects
+      with the saved objects APIs.
+
+
+      To manage a specific type of saved object, use the corresponding APIs.
+
+      For example, use:
+
+
+      [Data views](../group/endpoint-data-views)
+
+
+      Warning: Do not write documents directly to the `.kibana` index. When you
+      write directly to the `.kibana` index, the data becomes corrupted and
+      permanently breaks future Kibana versions.
     name: saved objects
+    x-displayName: Saved objects
   - description: 'SLO APIs enable you to define, manage and track service-level objectives'
     name: slo
   - name: system
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
@@ -27592,10 +27592,30 @@ tags:
   - name: Fleet uninstall tokens
   - description: Machine learning
     name: ml
-  - description: >-
-      Manage Kibana saved objects, including dashboards, visualizations, and
-      more.
+  - description: >
+      Export sets of saved objects that you want to import into {kib}, resolve
+      import errors, and rotate an encryption key for encrypted saved objects
+      with the saved objects APIs.
+
+
+      To manage a specific type of saved object, use the corresponding APIs.
+
+      For example, use:
+
+
+      * [Data views](../group/endpoint-data-views)
+
+      * [Spaces](https://www.elastic.co/guide/en/kibana/current/spaces-api.html)
+
+      * [Short
+      URLs](https://www.elastic.co/guide/en/kibana/current/short-urls-api.html)
+
+
+      Warning: Do not write documents directly to the `.kibana` index. When you
+      write directly to the `.kibana` index, the data becomes corrupted and
+      permanently breaks future Kibana versions.
     name: saved objects
+    x-displayName: Saved objects
   - description: 'SLO APIs enable you to define, manage and track service-level objectives'
     name: slo
   - name: system
diff --git a/oas_docs/overlays/kibana.overlays.serverless.yaml b/oas_docs/overlays/kibana.overlays.serverless.yaml
@@ -50,10 +50,6 @@ actions:
     description: Change displayName
     update:
       x-displayName: "Machine learning"
-  - target: '$.tags[?(@.name=="saved objects")]'
-    description: Change displayName
-    update:
-      x-displayName: "Saved objects"
   - target: '$.tags[?(@.name=="slo")]'
     description: Change displayName
     update:

diff --git a/oas_docs/overlays/kibana.overlays.yaml b/oas_docs/overlays/kibana.overlays.yaml
@@ -65,10 +65,6 @@ actions:
     description: Change displayName
     update:
       x-displayName: "Machine learning"
-  - target: '$.tags[?(@.name=="saved objects")]'
-    description: Change displayName
-    update:
-      x-displayName: "Saved objects"
   - target: '$.tags[?(@.name=="slo")]'
     description: Change displayName
     update:

diff --git a/packages/core/saved-objects/docs/openapi/bundled.json b/packages/core/saved-objects/docs/openapi/bundled.json
@@ -20,7 +20,8 @@
   "tags": [
     {
       "name": "saved objects",
-      "description": "Manage Kibana saved objects, including dashboards, visualizations, and more."
+      "x-displayName": "Saved objects",
+      "description": "Export sets of saved objects that you want to import into {kib}, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.\n\nTo manage a specific type of saved object, use the corresponding APIs.\nFor example, use:\n\n* [Data views](../group/endpoint-data-views)\n* [Spaces](https://www.elastic.co/guide/en/kibana/current/spaces-api.html)\n* [Short URLs](https://www.elastic.co/guide/en/kibana/current/short-urls-api.html)\n\nWarning: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future Kibana versions.\n"
     }
   ],
   "paths": {

diff --git a/packages/core/saved-objects/docs/openapi/bundled.yaml b/packages/core/saved-objects/docs/openapi/bundled.yaml
@@ -12,7 +12,18 @@ servers:
   - url: /
 tags:
   - name: saved objects
-    description: Manage Kibana saved objects, including dashboards, visualizations, and more.
+    x-displayName: Saved objects
+    description: |
+      Export sets of saved objects that you want to import into {kib}, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.
+
+      To manage a specific type of saved object, use the corresponding APIs.
+      For example, use:
+
+      * [Data views](../group/endpoint-data-views)
+      * [Spaces](https://www.elastic.co/guide/en/kibana/current/spaces-api.html)
+      * [Short URLs](https://www.elastic.co/guide/en/kibana/current/short-urls-api.html)
+
+      Warning: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future Kibana versions.
 paths:
   /api/encrypted_saved_objects/_rotate_key:
     post:

diff --git a/packages/core/saved-objects/docs/openapi/bundled_serverless.json b/packages/core/saved-objects/docs/openapi/bundled_serverless.json
@@ -25,7 +25,8 @@
   "tags": [
     {
       "name": "saved objects",
-      "description": "Manage Kibana saved objects, including dashboards, visualizations, and more."
+      "x-displayName": "Saved objects",
+      "description": "Export sets of saved objects that you want to import into {kib}, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.\n\nTo manage a specific type of saved object, use the corresponding APIs.\nFor example, use:\n\n[Data views](../group/endpoint-data-views)\n\nWarning: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future Kibana versions.\n"
     }
   ],
   "paths": {

diff --git a/packages/core/saved-objects/docs/openapi/bundled_serverless.yaml b/packages/core/saved-objects/docs/openapi/bundled_serverless.yaml
@@ -15,7 +15,16 @@ servers:
         default: localhost:5601
 tags:
   - name: saved objects
-    description: Manage Kibana saved objects, including dashboards, visualizations, and more.
+    x-displayName: Saved objects
+    description: |
+      Export sets of saved objects that you want to import into {kib}, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.
+
+      To manage a specific type of saved object, use the corresponding APIs.
+      For example, use:
+
+      [Data views](../group/endpoint-data-views)
+
+      Warning: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future Kibana versions.
 paths:
   /api/saved_objects/_export:
     post:

diff --git a/packages/core/saved-objects/docs/openapi/entrypoint.yaml b/packages/core/saved-objects/docs/openapi/entrypoint.yaml
@@ -10,7 +10,18 @@ info:
     url: https://www.elastic.co/licensing/elastic-license
 tags:
   - name: saved objects
-    description: Manage Kibana saved objects, including dashboards, visualizations, and more.
+    x-displayName: Saved objects
+    description: |
+      Export sets of saved objects that you want to import into {kib}, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.
+      
+      To manage a specific type of saved object, use the corresponding APIs.
+      For example, use:
+
+      * [Data views](../group/endpoint-data-views)
+      * [Spaces](https://www.elastic.co/guide/en/kibana/current/spaces-api.html)
+      * [Short URLs](https://www.elastic.co/guide/en/kibana/current/short-urls-api.html)
+
+      Warning: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future Kibana versions.
 servers:
   - url: /
 paths:

diff --git a/packages/core/saved-objects/docs/openapi/entrypoint_serverless.yaml b/packages/core/saved-objects/docs/openapi/entrypoint_serverless.yaml
@@ -10,7 +10,16 @@ info:
     url: https://www.elastic.co/licensing/elastic-license
 tags:
   - name: saved objects
-    description: Manage Kibana saved objects, including dashboards, visualizations, and more.
+    x-displayName: Saved objects
+    description: |
+      Export sets of saved objects that you want to import into {kib}, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.
+      
+      To manage a specific type of saved object, use the corresponding APIs.
+      For example, use:
+
+      [Data views](../group/endpoint-data-views)
+
+      Warning: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future Kibana versions.
 servers:
   - url: 'https://{kibana_url}'
     variables:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,5 +8,3 @@ For the latest details, refer to {api-kibana}/group/endpoint-data-views[data vie
		WARNING: Do not write documents directly to the `.kibana` index. When you write directly
		to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.

		WARNING: Use the data views APIs for managing data views instead of lower-level <<saved-objects-api, saved objects API>>.