Documentation for Saved Objects API (#19513)

* Adds documentation for Saved Objects API

Signed-off-by: Tyler Smalley <tyler.smalley@elastic.co>

* [DOCS] Moved Rest APIs in navigation

* docs: revise rest api intro

* docs: revise create object api details

* docs: revise saved object api intro

* docs: revise delete saved object api details

* docs: remove newline character from api response

* docs: get saved object api details

* docs: update saved object api details

* docs: fix title attribute in saved object api examples

* docs: bulk-get saved object api details

* docs: find saved object api details

* docs: add index-pattern to valid types in api

* docs: clarify sending multiple values in api

* docs: note that savedObjects.find is not safe for export

docs/api.asciidoc

@@ -0,0 +1,33 @@
+[[api]]
+= REST API
+
+[partintro]
+--
+Some of the features of Kibana are provided via a REST API, which is ideal for
+people that want to create an integration with Kibana or that want to automate
+certain aspects of configuring and deploying Kibana.
+
+Each API in this documentation should be clearly marked as either `stable`,
+`beta`, or `experimental`. If an API is not marked, it should be considered
+`experimental`.
+
+What do these labels mean?
+
+* *Stable* APIs should be safe to use extensively in production. Any breaking
+changes to these APIs should only occur in major versions and will be
+clearly documented in the breaking changes documentation for that release.
+* *Beta* APIs are on track to become stable, permanent features of Kibana.
+Caution should be exercised in their use since it is possible we'd have to make
+a breaking change to these APIs in a minor version, but we'll avoid this
+wherever possible.
+* *Experimental* APIs are just that - an experiment. An experimental API might
+have breaking changes in any version of Kibana, or it might even be removed
+entirely.
+
+[float]
+== APIs
+
+* <<saved-objects-api>>
+--
+
+include::api/saved-objects.asciidoc[]

docs/api/saved-objects.asciidoc

@@ -0,0 +1,24 @@
+[[saved-objects-api]]
+== Saved Objects API
+
+The saved objects API allows people to manage Kibana saved objects, including
+but not limited to dashboards, visualizations, and index patterns.
+
+Traditionally, developers would perform this level of integration by writing
+documents directly to the `.kibana` index. *Do not do this!* Writing directly
+to the `.kibana` index is not safe and it _will_ result in corrupted data that
+permanently breaks Kibana in a future version.
+
+* <<saved-objects-api-get>>
+* <<saved-objects-api-bulk-get>>
+* <<saved-objects-api-find>>
+* <<saved-objects-api-create>>
+* <<saved-objects-api-update>>
+* <<saved-objects-api-delete>>
+
+include::saved-objects/get.asciidoc[]
+include::saved-objects/bulk_get.asciidoc[]
+include::saved-objects/find.asciidoc[]
+include::saved-objects/create.asciidoc[]
+include::saved-objects/update.asciidoc[]
+include::saved-objects/delete.asciidoc[]

docs/api/saved-objects/bulk_get.asciidoc

@@ -0,0 +1,81 @@
+[[saved-objects-api-bulk-get]]
+=== Bulk Get Objects
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The bulk-get saved object API enables you to retrieve multiple Kibana saved
+objects by id.
+
+==== Request
+
+`POST /api/saved_objects/_bulk_get`
+
+==== Request Body
+
+The request body must be a JSON array containing objects, each of which
+contains the following properties:
+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`
+
+`id` (required)::
+  (string) ID of object to retrieve
+
+==== Response body
+
+The response body will have a top level `saved_objects` property that contains
+an array of objects, which 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.
+
+For any saved object that could not be found, an error object will exist in its
+place.
+
+==== Examples
+
+The following example attempts to retrieve an index pattern with id
+`my-pattern` and a dashboard with id `my-dashboard`, but only the index pattern
+exists.
+
+[source,js]
+--------------------------------------------------
+POST api/saved_objects/_bulk_get
+[
+  {
+    "type": "index-pattern",
+    "id": "my-pattern"
+  },
+  {
+    "type": "dashboard",
+    "id": "my-dashboard"
+  }
+]
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "saved_objects": [
+    {
+      "id": "my-pattern",
+      "type": "index-pattern",
+      "version": 1,
+      "attributes": {
+        "title": "my-pattern-*"
+      }
+    },
+    {
+      "id": "my-dashboard",
+      "type": "dashboard",
+      "error": {
+        "statusCode": 404,
+        "message": "Not found"
+      }
+    }
+  ]
+}
+--------------------------------------------------

docs/api/saved-objects/create.asciidoc

@@ -0,0 +1,73 @@
+[[saved-objects-api-create]]
+=== Create Object
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The create saved object API enables you to persist a Kibana saved object.
+
+==== Request
+
+`POST /api/saved_objects/<type>` +
+
+`POST /api/saved_objects/<type>/<id>`
+
+==== Path Parameters
+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`
+
+`id` (optional)::
+  (string) Enables specifying an ID to use, as opposed to one being randomly generated
+
+
+==== Query Parameters
+
+`overwrite` (optional)::
+  (boolean) If true, will overwrite the document with the same ID.
+
+
+==== Request Body
+
+`attributes` (required)::
+  (object) The data to persist
+
+
+==== Examples
+
+The following example creates an index pattern object with a pattern of
+`my-pattern-*`.
+
+[source,js]
+--------------------------------------------------
+POST api/saved_objects/index-pattern/my-pattern
+{
+  "attributes": {
+    "title": "my-pattern-*"
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "my-pattern", <1>
+  "type": "index-pattern",
+  "version": 1,
+  "attributes": {
+    "title": "my-pattern-*"
+  }
+}
+--------------------------------------------------
+
+<1> If `my-pattern` was not specified in the path, a unique ID would have been
+generated.
+
+==== Known issues
+
+1. *Attributes are not validated at creation time*. This means you can pass
+arbitrary and ill-formed data into this API that can break Kibana. Make sure
+any data you send to this API is properly formed.

docs/api/saved-objects/delete.asciidoc

@@ -0,0 +1,32 @@
+[[saved-objects-api-delete]]
+=== Delete Object
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The delete saved object API permanently removes a Kibana saved object. Once a
+saved object has been deleted, _it cannot be recovered_.
+
+==== Request
+
+`DELETE /api/saved_objects/<type>/<id>`
+
+==== Path Parameters
+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`
+
+`id` (required)::
+  (string) Object ID being removed
+
+
+==== Examples
+
+The following example deletes an index pattern object with an ID of `my-pattern`
+
+[source,js]
+--------------------------------------------------
+DELETE api/saved_objects/index-pattern/my-pattern
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200`.

docs/api/saved-objects/find.asciidoc

@@ -0,0 +1,84 @@
+[[saved-objects-api-find]]
+=== Find Objects
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The find saved object API enables you to retrieve a paginated set of Kibana
+saved objects by various conditions.
+
+==== Request
+
+`GET /api/saved_objects/_find`
+
+==== Query Parameters
+
+`per_page` (optional)::
+  (number) The number of objects to return per page
+`page` (optional)::
+  (number) The page of objects to return
+`type` (optional)::
+  (array|string) The saved object type(s) that the response should be limited to
+`search` (optional)::
+  (string) A {ref}/query-dsl-simple-query-string-query.html[simple_query_string] Elasticsearch query to filter the objects in the response
+`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 on which the response will be sorted
+
+[NOTE]
+==============================================
+
+As objects change in Kibana, the results on each page of this response can
+change. This makes the `find` API suitable for traditional paginated results
+but not a reliable way to safely export large amounts of data.
+
+==============================================
+
+
+==== Examples
+
+The following example attempts to find index patterns with titles that start
+with `my`:
+
+[source,js]
+--------------------------------------------------
+GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "total": 1,
+  "data": [
+    {
+      "id": "my-pattern",
+      "type": "index-pattern",
+      "version": 1,
+      "attributes": {
+        "title": "my-pattern-*"
+      }
+    }
+  ]
+}
+--------------------------------------------------
+
+[NOTE]
+.Multiple values for a parameter
+==============================================
+
+For parameters that can accept multiple values (e.g. `fields`), repeat the
+query parameter for each value:
+
+[source,js]
+--------------------------------------------------
+GET api/saved_objects/_find?fields=id&fields=title
+--------------------------------------------------
+// KIBANA
+
+==============================================

docs/api/saved-objects/get.asciidoc

@@ -0,0 +1,46 @@
+[[saved-objects-api-get]]
+=== Get Object
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The get saved object API enables you to retrieve a single Kibana saved object
+by id.
+
+==== Request
+
+`GET /api/saved_objects/<type>/<id>`
+
+==== Path Parameters
+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`
+
+`id` (required)::
+  (string) ID of object to retrieve
+
+
+==== Examples
+
+The following example retrieves the index pattern object with an id of
+`my-pattern`.
+
+[source,js]
+--------------------------------------------------
+GET api/saved_objects/index-pattern/my-pattern
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "my-pattern",
+  "type": "index-pattern",
+  "version": 1,
+  "attributes": {
+    "title": "my-pattern-*"
+  }
+}
+--------------------------------------------------

docs/api/saved-objects/update.asciidoc

@@ -0,0 +1,63 @@
+[[saved-objects-api-update]]
+=== Update Object
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The update saved object API enables you to update the attributes for an
+existing Kibana saved object.
+
+==== Request
+
+`PUT /api/saved_objects/<type>/<id>`
+
+==== Path Parameters
+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`
+
+`id` (required)::
+  (string) ID of object to update
+
+
+==== Request Body
+
+`attributes` (required)::
+  (object) The data to persist
+
+
+==== Examples
+
+The following example updates an existing index pattern object identified as
+`my-pattern` with a different index pattern title.
+
+[source,js]
+--------------------------------------------------
+PUT api/saved_objects/index-pattern/my-pattern
+{
+  "attributes": {
+    "title": "some-other-pattern-*"
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "my-pattern",
+  "type": "index-pattern",
+  "version": 2,
+  "attributes": {
+    "title": "some-other-pattern-*"
+  }
+}
+--------------------------------------------------
+
+==== Known issues
+
+1. *Attributes are not validated at update time*. This means you can pass
+arbitrary and ill-formed data into this API that can break Kibana. Make sure
+any data you send to this API is properly formed.

docs/index.asciidoc

@@ -67,6 +67,8 @@ include::management/dashboard_only_mode/index.asciidoc[]
 
 include::reporting/index.asciidoc[]
 
+include::api.asciidoc[]
+
 include::plugins.asciidoc[]
 
 include::development.asciidoc[]