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

Fix https://github.com/elastic/kibana/issues/191534 The deprecation warning in the Kibana Saved Objects API main page was removed in https://github.com/elastic/kibana/pull/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 <lcawley@elastic.co>
2025-04-24 01:38:56 -04:00 · 2024-08-29 13:04:00 -07:00 · 2024-08-29 13:04:00 -07:00 · dd221a7be1
commit dd221a7be1
parent 6826eafe17
15 changed files with 101 additions and 32 deletions
--- 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[]
--- 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>>.
-
--- 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: 

--- 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].
--- 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[]
--- 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
--- 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
--- 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:
--- 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:
--- 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": {
--- 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:
--- 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": {
--- 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:
--- 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:
--- 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: