[DOCS] Add space_id path parameter to saved_object APIs (#47627) (#60969)

* [DOCS] Add space_id path parameter to saved_object APIs * [DOCS] Apply suggested edits for #47627 * [DOCS] Apply suggested edits for #47627 to delete API
2025-04-24 01:38:56 -04:00 · 2020-03-23 15:06:22 -06:00 · 2020-03-23 15:06:22 -06:00 · 746662cab4
commit 746662cab4
parent bc82d6d0b1
10 changed files with 172 additions and 47 deletions
--- a/docs/api/saved-objects/bulk_create.asciidoc
+++ b/docs/api/saved-objects/bulk_create.asciidoc
@ -11,6 +11,15 @@ experimental[] Create multiple {kib} saved objects.

 `POST /api/saved_objects/_bulk_create`

+`POST /s/<space_id>/api/saved_objects/_bulk_create`
+
+
+[[saved-objects-api-bulk-create-path-params]]
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
+
 [[saved-objects-api-bulk-create-query-params]]
 ==== Query parameters

@ -38,7 +47,7 @@ experimental[] Create multiple {kib} saved objects.
 [[saved-objects-api-bulk-create-response-body]]
 ==== Response body

-`saved_objects`:: 
+`saved_objects`::
  (array) Top-level property the contains objects that represent the response for each of the requested objects. The order of the objects in the response is identical to the order of the objects in the request.

 Saved objects that are unable to persist are replaced with an error object.
@ -46,13 +55,13 @@ Saved objects that are unable to persist are replaced with an error object.
 [[saved-objects-api-bulk-create-codes]]
 ==== Response code

-`200`:: 
+`200`::
  Indicates a successful call.

 [[saved-objects-api-bulk-create-example]]
 ==== Example

-Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID: 
+Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:

 [source,js]
 --------------------------------------------------
@ -67,7 +76,7 @@ POST api/saved_objects/_bulk_create
  },
  {
    "type": "dashboard",
-    "id": "my-dashboard",
+    "id": "be3733a0-9efe-11e7-acb3-3dab96693fab",
    "attributes": {
      "title": "Look at my dashboard"
    }
@ -91,7 +100,7 @@ The API returns the following:
      }
    },
    {
-      "id": "my-dashboard",
+      "id": "be3733a0-9efe-11e7-acb3-3dab96693fab",
      "type": "dashboard",
      "error": {
        "statusCode": 409,
--- a/docs/api/saved-objects/bulk_get.asciidoc
+++ b/docs/api/saved-objects/bulk_get.asciidoc
@ -11,6 +11,14 @@ experimental[] Retrieve multiple {kib} saved objects by ID.

 `POST /api/saved_objects/_bulk_get`

+`POST /s/<space_id>/api/saved_objects/_bulk_get`
+
+[[saved-objects-api-bulk-get-path-params]]
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 [[saved-objects-api-bulk-get-request-body]]
 ==== Request Body

@ -18,15 +26,15 @@ experimental[] Retrieve multiple {kib} saved objects by ID.
  (Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.

 `id`::
-  (Required, string) ID of the retrieved object.
+  (Required, string) ID of the retrieved object. The ID includes the {kib} unique identifier or a custom identifier.

 `fields`::
  (Optional, array) The fields returned in the object response.
-  
+
 [[saved-objects-api-bulk-get-response-body]]
 ==== Response body

-`saved_objects`:: 
+`saved_objects`::
  (array) Top-level property the contains objects that represent the response for each of the requested objects. The order of the objects in the response is identical to the order of the objects in the request.

 Saved objects that are unable to persist are replaced with an error object.
@ -34,13 +42,13 @@ Saved objects that are unable to persist are replaced with an error object.
 [[saved-objects-api-bulk-get-body-codes]]
 ==== Response code

-`200`:: 
-  Indicates a successfully call.
+`200`::
+  Indicates a successful call.

 [[saved-objects-api-bulk-get-body-example]]
 ==== Example

-Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID: 
+Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:

 [source,js]
 --------------------------------------------------
@ -52,7 +60,7 @@ POST api/saved_objects/_bulk_get
  },
  {
    "type": "dashboard",
-    "id": "my-dashboard"
+    "id": "be3733a0-9efe-11e7-acb3-3dab96693fab"
  }
 ]
 --------------------------------------------------
--- a/docs/api/saved-objects/create.asciidoc
+++ b/docs/api/saved-objects/create.asciidoc
@ -13,9 +13,14 @@ experimental[] Create {kib} saved objects.

 `POST /api/saved_objects/<type>/<id>`

+`POST /s/<space_id>/saved_objects/<type>`
+
 [[saved-objects-api-create-path-params]]
 ==== Path parameters

+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 `<type>`::
  (Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.

@ -44,9 +49,9 @@ any data that you send to the API is properly formed.
 [[saved-objects-api-create-request-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.
-    
+
 [[saved-objects-api-create-example]]
 ==== Example

--- a/docs/api/saved-objects/delete.asciidoc
+++ b/docs/api/saved-objects/delete.asciidoc
@ -13,9 +13,14 @@ WARNING: Once you delete a saved object, _it cannot be recovered_.

 `DELETE /api/saved_objects/<type>/<id>`

+`DELETE /s/<space_id>/api/saved_objects/<type>/<id>`
+
 [[saved-objects-api-delete-path-params]]
 ==== Path parameters

+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 `type`::
  (Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.

@ -25,7 +30,7 @@ WARNING: Once you delete a saved object, _it cannot be recovered_.
 [[saved-objects-api-delete-response-codes]]
 ==== Response code

-`200`:: 
+`200`::
  Indicates a successful call.

 ==== Examples
--- a/docs/api/saved-objects/export.asciidoc
+++ b/docs/api/saved-objects/export.asciidoc
@ -11,15 +11,23 @@ experimental[] Retrieve sets of saved objects that you want to import into {kib}

 `POST /api/saved_objects/_export`

+`POST /s/<space_id>/api/saved_objects/_export`
+
+[[saved-objects-api-export-path-params]]
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 [[saved-objects-api-export-request-request-body]]
 ==== Request body

 `type`::
  (Optional, array|string) The saved object types to include in the export.
-  
+
 `objects`::
  (Optional, array) A list of objects to export.
-  
+
 `includeReferencesDeep`::
  (Optional, boolean) Includes all of the referenced objects in the exported objects.

@ -50,7 +58,7 @@ When `excludeExportDetails=false` (the default) we append an export result detai
 [[export-objects-api-create-request-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.

 [[ssaved-objects-api-create-example]]
--- a/docs/api/saved-objects/find.asciidoc
+++ b/docs/api/saved-objects/find.asciidoc
@ -11,33 +11,41 @@ experimental[] Retrieve a paginated set of {kib} saved objects by various condit

 `GET /api/saved_objects/_find`

+`GET /s/<space_id>/api/saved_objects/_find`
+
+[[saved-objects-api-find-path-params]]
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 [[saved-objects-api-find-query-params]]
 ==== Query Parameters

 `type`::
  (Required, array|string) The saved object types to include in the export.
-  
+
 `per_page`::
  (Optional, number) The number of objects to return per page.
-  
+
 `page`::
  (Optional, number) The page of objects to return.
-  
+
 `search`::
  (Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the objects in the response.
-  
+
 `default_search_operator`::
  (Optional, string) The default operator to use for the `simple_query_string`.
-  
+
 `search_fields`::
  (Optional, array|string) The fields to perform the `simple_query_string` parsed query against.
-  
+
 `fields`::
  (Optional, array|string) The fields to return in the response.
-  
+
 `sort_field`::
  (Optional, string) The field that sorts the response.
-  
+
 `has_reference`::
  (Optional, object) Filters to objects that have a relationship with the type and ID combination.

@ -52,7 +60,7 @@ change. Use the find API for traditional paginated results, but avoid using it t
 [[saved-objects-api-find-request-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.

 ==== Examples
@ -92,4 +100,3 @@ query parameter for each value:
 GET api/saved_objects/_find?fields=id&fields=title
 --------------------------------------------------
 // KIBANA
-
--- a/docs/api/saved-objects/get.asciidoc
+++ b/docs/api/saved-objects/get.asciidoc
@ -11,9 +11,15 @@ experimental[] Retrieve a single {kib} saved object by ID.

 `GET /api/saved_objects/<type>/<id>`

+`GET /s/<space_id>/api/saved_objects/<type>/<id>`
+
 [[saved-objects-api-get-params]]
 ==== Path parameters

+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
+
 `type`::
  (Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.

@ -23,10 +29,10 @@ experimental[] Retrieve a single {kib} saved object by ID.
 [[saved-objects-api-get-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.

-[[saved-objects-api-get-example]]      
+[[saved-objects-api-get-example]]
 ==== Example

 Retrieve the index pattern object with the `my-pattern` ID:
@ -50,3 +56,59 @@ The API returns the following:
  }
 }
 --------------------------------------------------
+
+The following example retrieves a dashboard object in the `testspace` by id.
+
+[source,js]
+--------------------------------------------------
+GET /s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "7adfa750-4c81-11e8-b3d7-01146121b73d",
+  "type": "dashboard",
+  "updated_at": "2019-07-23T00:11:07.059Z",
+  "version": "WzQ0LDFd",
+  "attributes": {
+    "title": "[Flights] Global Flight Dashboard",
+    "hits": 0,
+    "description": "Analyze mock flight data for ES-Air, Logstash Airways, Kibana Airlines and JetBeats",
+    "panelsJSON": "[{\"panelIndex\":\"1\",\"gridData\":{\"x\":0,\"y\":0,\"w\":32,\"h\":7,\"i\":\"1\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_0\"},{\"panelIndex\":\"3\",\"gridData\":{\"x\":17,\"y\":7,\"w\":23,\"h\":12,\"i\":\"3\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Average Ticket Price\":\"#0A50A1\",\"Flight Count\":\"#82B5D8\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_1\"},{\"panelIndex\":\"4\",\"gridData\":{\"x\":0,\"y\":85,\"w\":48,\"h\":15,\"i\":\"4\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_2\"},{\"panelIndex\":\"5\",\"gridData\":{\"x\":0,\"y\":7,\"w\":17,\"h\":12,\"i\":\"5\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"ES-Air\":\"#447EBC\",\"JetBeats\":\"#65C5DB\",\"Kibana Airlines\":\"#BA43A9\",\"Logstash Airways\":\"#E5AC0E\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_3\"},{\"panelIndex\":\"6\",\"gridData\":{\"x\":24,\"y\":33,\"w\":24,\"h\":14,\"i\":\"6\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Carrier Delay\":\"#5195CE\",\"Late Aircraft Delay\":\"#1F78C1\",\"NAS Delay\":\"#70DBED\",\"No Delay\":\"#BADFF4\",\"Security Delay\":\"#052B51\",\"Weather Delay\":\"#6ED0E0\"}}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_4\"},{\"panelIndex\":\"7\",\"gridData\":{\"x\":24,\"y\":19,\"w\":24,\"h\":14,\"i\":\"7\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_5\"},{\"panelIndex\":\"10\",\"gridData\":{\"x\":0,\"y\":35,\"w\":24,\"h\":12,\"i\":\"10\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Count\":\"#1F78C1\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_6\"},{\"panelIndex\":\"13\",\"gridData\":{\"x\":10,\"y\":19,\"w\":14,\"h\":8,\"i\":\"13\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Count\":\"#1F78C1\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_7\"},{\"panelIndex\":\"14\",\"gridData\":{\"x\":10,\"y\":27,\"w\":14,\"h\":8,\"i\":\"14\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Count\":\"#1F78C1\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_8\"},{\"panelIndex\":\"18\",\"gridData\":{\"x\":24,\"y\":70,\"w\":24,\"h\":15,\"i\":\"18\"},\"embeddableConfig\":{\"mapCenter\":[27.421687059550266,15.371002131141724],\"mapZoom\":1},\"version\":\"6.3.0\",\"panelRefName\":\"panel_9\"},{\"panelIndex\":\"21\",\"gridData\":{\"x\":0,\"y\":62,\"w\":48,\"h\":8,\"i\":\"21\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_10\"},{\"panelIndex\":\"22\",\"gridData\":{\"x\":32,\"y\":0,\"w\":16,\"h\":7,\"i\":\"22\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_11\"},{\"panelIndex\":\"23\",\"gridData\":{\"x\":0,\"y\":70,\"w\":24,\"h\":15,\"i\":\"23\"},\"embeddableConfig\":{\"mapCenter\":[42.19556096274418,9.536742995308601e-7],\"mapZoom\":1},\"version\":\"6.3.0\",\"panelRefName\":\"panel_12\"},{\"panelIndex\":\"25\",\"gridData\":{\"x\":0,\"y\":19,\"w\":10,\"h\":8,\"i\":\"25\"},\"embeddableConfig\":{\"vis\":{\"defaultColors\":{\"0 - 50\":\"rgb(247,251,255)\",\"100 - 150\":\"rgb(107,174,214)\",\"150 - 200\":\"rgb(33,113,181)\",\"200 - 250\":\"rgb(8,48,107)\",\"50 - 100\":\"rgb(198,219,239)\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_13\"},{\"panelIndex\":\"27\",\"gridData\":{\"x\":0,\"y\":27,\"w\":10,\"h\":8,\"i\":\"27\"},\"embeddableConfig\":{\"vis\":{\"defaultColors\":{\"0 - 50\":\"rgb(247,251,255)\",\"100 - 150\":\"rgb(107,174,214)\",\"150 - 200\":\"rgb(33,113,181)\",\"200 - 250\":\"rgb(8,48,107)\",\"50 - 100\":\"rgb(198,219,239)\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_14\"},{\"panelIndex\":\"28\",\"gridData\":{\"x\":0,\"y\":47,\"w\":24,\"h\":15,\"i\":\"28\"},\"embeddableConfig\":{\"vis\":{\"defaultColors\":{\"0 -* Connection #0 to host 69c72adb58fa46c69a01afdf4a6cbfd3.us-west1.gcp.cloud.es.io left intact\n 11\":\"rgb(247,251,255)\",\"11 - 22\":\"rgb(208,225,242)\",\"22 - 33\":\"rgb(148,196,223)\",\"33 - 44\":\"rgb(74,152,201)\",\"44 - 55\":\"rgb(23,100,171)\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_15\"},{\"panelIndex\":\"29\",\"gridData\":{\"x\":40,\"y\":7,\"w\":8,\"h\":6,\"i\":\"29\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_16\"},{\"panelIndex\":\"30\",\"gridData\":{\"x\":40,\"y\":13,\"w\":8,\"h\":6,\"i\":\"30\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_17\"},{\"panelIndex\":\"31\",\"gridData\":{\"x\":24,\"y\":47,\"w\":24,\"h\":15,\"i\":\"31\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_18\"}]",
+    "optionsJSON": "{\"hidePanelTitles\":false,\"useMargins\":true}",
+    "version": 1,
+    "timeRestore": true,
+    "timeTo": "now",
+    "timeFrom": "now-24h",
+    "refreshInterval": {
+      "display": "15 minutes",
+      "pause": false,
+      "section": 2,
+      "value": 900000
+    },
+    "kibanaSavedObjectMeta": {
+      "searchSourceJSON": "{\"query\":{\"language\":\"kuery\",\"query\":\"\"},\"filter\":[],\"highlightAll\":true,\"version\":true}"
+    }
+  },
+  "references": [
+    {
+      "name": "panel_0",
+      "type": "visualization",
+      "id": "aeb212e0-4c84-11e8-b3d7-01146121b73d"
+    },
+    . . .
+    {
+      "name": "panel_18",
+      "type": "visualization",
+      "id": "ed78a660-53a0-11e8-acbd-0be0ad9d822b"
+    }
+  ],
+  "migrationVersion": {
+    "dashboard": "7.0.0"
+  }
+}
+--------------------------------------------------
--- a/docs/api/saved-objects/import.asciidoc
+++ b/docs/api/saved-objects/import.asciidoc
@ -11,8 +11,16 @@ experimental[] Create sets of {kib} saved objects from a file created by the exp

 `POST /api/saved_objects/_import`

+`POST /s/<space_id>/api/saved_objects/_import`
+
+[[saved-objects-api-import-path-params]]
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 [[saved-objects-api-import-query-params]]
-==== Query parameter
+==== Query parameters

 `overwrite`::
  (Optional, boolean) Overwrites saved objects.
@ -28,19 +36,19 @@ The request body must include the multipart/form-data type.
 [[saved-objects-api-import-response-body]]
 ==== Response body

-`success`:: 
-  Top-level property that indicates if the import was successful. 
+`success`::
+  Top-level property that indicates if the import was successful.

-`successCount`:: 
+`successCount`::
  Indicates the number of successfully imported records.

 `errors`::
  (array) Indicates the import was unsuccessful and specifies the objects that failed to import.
-  
+
 [[saved-objects-api-import-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.

 ==== Examples
--- a/docs/api/saved-objects/resolve_import_errors.asciidoc
+++ b/docs/api/saved-objects/resolve_import_errors.asciidoc
@ -4,9 +4,9 @@
 <titleabbrev>Resolve import errors</titleabbrev>
 ++++

-experimental[] Resolve errors from the import API. 
+experimental[] Resolve errors from the import API.

-To resolve errors, you can: 
+To resolve errors, you can:

 * Retry certain saved objects

@ -19,6 +19,14 @@ To resolve errors, you can:

 `POST /api/saved_objects/_resolve_import_errors`

+`POST /s/<space_id>/api/saved_objects/_resolve_import_errors`
+
+[[saved-objects-api-resolve-import-errors-path-params]]
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
 [[saved-objects-api-resolve-import-errors-request-body]]
 ==== Request body

@ -33,19 +41,19 @@ The request body must include the multipart/form-data type.
 [[saved-objects-api-resolve-import-errors-response-body]]
 ==== Response body

-`success`:: 
+`success`::
  Top-level property that indicates if the errors successfully resolved.
-  
-`successCount`:: 
+
+`successCount`::
  Indicates the number of successfully resolved records.

 `errors`::
  (array) Specifies the objects that failed to resolve.
-  
+
 [[saved-objects-api-resolve-import-errors-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.

 [[saved-objects-api-resolve-import-errors-example]]
--- a/docs/api/saved-objects/update.asciidoc
+++ b/docs/api/saved-objects/update.asciidoc
@ -11,8 +11,13 @@ experimental[] Update the attributes for existing {kib} saved objects.

 `PUT /api/saved_objects/<type>/<id>`

+`PUT /s/<space_id>/api/saved_objects/<type>/<id>`
+
 [[saved-objects-api-update-path-params]]
-==== Path Parameters
+==== Path parameters
+
+`space_id`::
+  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.

 `type`::
  (Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.
@ -21,7 +26,7 @@ experimental[] Update the attributes for existing {kib} saved objects.
  (Required, string) The object ID to update.

 [[saved-objects-api-update-request-body]]
-==== Request Body
+==== Request body

 `attributes`::
  (Required, object) The data to persist.
@ -30,11 +35,11 @@ WARNING: When you update, attributes are not validated, which allows you to pass

 `references`::
  (Optional, array) Objects with `name`, `id`, and `type` properties that describe the other saved objects this object references. To refer to the other saved object, use `name` in the attributes, but never the `id`, which automatically updates during migrations or import/export.
-  
+
 [[saved-objects-api-update-errors-codes]]
 ==== Response code

-`200`:: 
+`200`::
    Indicates a successful call.

 [[saved-objects-api-update-example]]