docs: dashboard import/export API (#22835)

* docs: dashboard import/export API

* docs: clarify response handling of errors in import api

docs/api.asciidoc

@@ -29,10 +29,12 @@ entirely.
 
 * <<role-management-api>>
 * <<saved-objects-api>>
+* <<dashboard-import-api>>
 * <<logstash-configuration-management-api>>
 --
 
 include::api/role-management.asciidoc[]
 include::api/saved-objects.asciidoc[]
+include::api/dashboard-import.asciidoc[]
 include::api/logstash-configuration-management.asciidoc[]
 

docs/api/dashboard-import.asciidoc

@@ -0,0 +1,17 @@
+[[dashboard-import-api]]
+== Dashboard Import API
+
+The dashboard import/export APIs allow people to import dashboards along with
+all of their corresponding saved objects such as visualizations, saved
+searches, 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.
+
+* <<dashboard-import-api-import>>
+* <<dashboard-import-api-export>>
+
+include::dashboard-import/import.asciidoc[]
+include::dashboard-import/export.asciidoc[]

docs/api/dashboard-import/export.asciidoc

@@ -0,0 +1,38 @@
+[[dashboard-import-api-export]]
+=== Export Dashboard
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The dashboard export API allows people to export dashboards along with all of
+their corresponding saved objects such as visualizations, saved searches, and
+index patterns.
+
+==== Request
+
+`GET /api/kibana/dashboards/export`
+
+==== Query Parameters
+
+`dashboard` (optional)::
+  (array|string) The id(s) of the dashboard(s) to export
+
+==== Response body
+
+The response body will have a top level `objects` property that contains an
+array of saved objects. The order of these objects is not guaranteed. You
+should use this exact response body as the request body for the corresponding
+<<dashboard-import-api-import, Import Dashboard API>>.
+
+==== Examples
+
+The following example exports all saved objects associated with and including
+the dashboard with id `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`.
+
+[source,js]
+--------------------------------------------------
+GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` along with the exported
+objects as the response body.

docs/api/dashboard-import/import.asciidoc

@@ -0,0 +1,96 @@
+[[dashboard-import-api-import]]
+=== Import Dashboard
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The dashboard import API allows people to import dashboards along with all of
+their corresponding saved objects such as visualizations, saved searches, and
+index patterns.
+
+==== Request
+
+`POST /api/kibana/dashboards/import`
+
+==== Query Parameters
+
+`force` (optional)::
+  (boolean) Overwrite any existing objects on id conflict
+`exclude` (optional)::
+  (array) Saved object types that should not be imported
+
+==== Request Body
+
+The request body is JSON, but you should not manually construct a payload to
+this endpoint. Instead, use the complete response body from the
+<<dashboard-import-api-export, Export Dashboard API>> as the request body to
+this import API.
+
+==== Response body
+
+The response body will have a top level `objects` property that contains an
+array of the saved objects that were created.
+
+==== Examples
+
+The following example imports saved objects associated with and including the
+dashboard with id `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`.
+
+[source,js]
+--------------------------------------------------
+POST api/kibana/dashboards/import?exclude=index-pattern
+{
+  "objects": [
+    {
+      "id": "80b956f0-b2cd-11e8-ad8e-85441f0c2e5c",
+      "type": "visualization",
+      "updated_at": "2018-09-07T18:40:33.247Z",
+      "version": 1,
+      "attributes": {
+        "title": "Count Example",
+        "visState": "{\"title\":\"Count Example\",\"type\":\"metric\",\"params\":{\"addTooltip\":true,\"addLegend\":false,\"type\":\"metric\",\"metric\":{\"percentageMode\":false,\"useRanges\":false,\"colorSchema\":\"Green to Red\",\"metricColorMode\":\"None\",\"colorsRange\":[{\"from\":0,\"to\":10000}],\"labels\":{\"show\":true},\"invertColors\":false,\"style\":{\"bgFill\":\"#000\",\"bgColor\":false,\"labelColor\":false,\"subText\":\"\",\"fontSize\":60}}},\"aggs\":[{\"id\":\"1\",\"enabled\":true,\"type\":\"count\",\"schema\":\"metric\",\"params\":{}}]}",
+        "uiStateJSON": "{}",
+        "description": "",
+        "version": 1,
+        "kibanaSavedObjectMeta": {
+          "searchSourceJSON": "{\"index\":\"90943e30-9a47-11e8-b64d-95841ca0b247\",\"query\":{\"query\":\"\",\"language\":\"lucene\"},\"filter\":[]}"
+        }
+      }
+    },
+    {
+      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
+      "type": "index-pattern",
+      "updated_at": "2018-09-07T18:39:47.683Z",
+      "version": 1,
+      "attributes": {
+        "title": "kibana_sample_data_logs",
+        "timeFieldName": "timestamp",
+        "fields": "<truncated for example>",
+        "fieldFormatMap": "{\"hour_of_day\":{}}"
+      }
+    },
+    {
+      "id": "942dcef0-b2cd-11e8-ad8e-85441f0c2e5c",
+      "type": "dashboard",
+      "updated_at": "2018-09-07T18:41:05.887Z",
+      "version": 1,
+      "attributes": {
+        "title": "Example Dashboard",
+        "hits": 0,
+        "description": "",
+        "panelsJSON": "[{\"gridData\":{\"w\":24,\"h\":15,\"x\":0,\"y\":0,\"i\":\"1\"},\"version\":\"7.0.0-alpha1\",\"panelIndex\":\"1\",\"type\":\"visualization\",\"id\":\"80b956f0-b2cd-11e8-ad8e-85441f0c2e5c\",\"embeddableConfig\":{}}]",
+        "optionsJSON": "{\"darkTheme\":false,\"useMargins\":true,\"hidePanelTitles\":false}",
+        "version": 1,
+        "timeRestore": false,
+        "kibanaSavedObjectMeta": {
+          "searchSourceJSON": "{\"query\":{\"query\":\"\",\"language\":\"lucene\"},\"filter\":[]}"
+        }
+      }
+    }
+  ]
+}
+--------------------------------------------------
+// KIBANA
+
+A response code of `200` will be returned even if there are errors importing
+individual saved objects. In that case, error information will be returned in
+the response body on an object-by-object basis.