[Docs] Index patterns REST API docs

docs/api/index-patterns.asciidoc

@@ -0,0 +1,27 @@
+[[index-patterns-api]]
+== Index patterns APIs
+
+experimental[] Manage {kib} index patterns using REST 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.
+
+WARNING: Prefer using index patterns API for managing {kib} index patterns instead of lower-level <<saved-objects-api, saved objects API>>.
+
+The following index patterns APIs are available: 
+
+* Index patterns
+    ** <<index-patterns-api-get, Get index pattern API>> to retrieve a single {kib} index pattern
+    ** <<index-patterns-api-create, Create index pattern API>> to create {kib} index pattern
+    ** <<index-patterns-api-update, Update index pattern API>> to partially updated {kib} index pattern
+    ** <<index-patterns-api-delete, Delete index pattern API>> to delete {kib} index pattern
+* Fields
+    ** <<index-patterns-fields-api-update, Update index pattern field>> to change field metadata, such as `count`, `customLabel` and `format`.
+
+
+
+include::index-patterns/get.asciidoc[]
+include::index-patterns/create.asciidoc[]
+include::index-patterns/update.asciidoc[]
+include::index-patterns/delete.asciidoc[]
+include::index-patterns/update-fields.asciidoc[]

docs/api/index-patterns/create.asciidoc

@@ -0,0 +1,102 @@
+[[index-patterns-api-create]]
+=== Create index pattern API
+++++
+<titleabbrev>Create index pattern</titleabbrev>
+++++
+
+experimental[] Create {kib} index pattern.
+
+[[index-patterns-api-create-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/index_patterns/index_pattern`
+
+`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern`
+
+[[index-patterns-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.
+
+[[index-patterns-api-create-body-params]]
+==== Request body
+
+`override`:: (Optional, boolean) If should override an existing index pattern if an
+index pattern with the provided title already exists. Defaults to false.
+
+`refresh_fields`:: (Optional, boolean) If to reload index pattern fields after
+the index pattern is stored. Defaults to false.
+
+`index_pattern`:: (Required, object) Index pattern spec object. All fields are optional. See example request below.
+
+[[index-patterns-api-create-request-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[index-patterns-api-create-example]]
+==== Examples
+
+Create an index pattern with a custom title:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/index_patterns/index_pattern
+{
+  "index_pattern": {
+     "title": "hello"
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+Customize creation behavior:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/index_patterns/index_pattern
+{
+  "override": false,
+  "refresh_fields": true,
+  "index_pattern": {
+     "title": "hello"
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+At creation all index pattern fields are optional, and you can provide them:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/index_patterns/index_pattern
+{
+  "index_pattern": {
+      "id": "...",
+      "version": "...",
+      "title": "...",
+      "type": "...",
+      "timeFieldName": "...",
+      "sourceFilters": [],
+      "fields": {},
+      "typeMeta": {},
+      "fieldFormats": {},
+      "fieldAttrs": {},
+      "allowNoIndex": "..."
+    }
+}
+--------------------------------------------------
+// KIBANA
+
+
+The API returns created index pattern object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {...}
+}
+--------------------------------------------------
+

docs/api/index-patterns/delete.asciidoc

@@ -0,0 +1,41 @@
+[[index-patterns-api-delete]]
+=== Delete index pattern API
+++++
+<titleabbrev>Delete index pattern</titleabbrev>
+++++
+
+experimental[] Delete {kib} index pattern.
+
+WARNING: Once you delete an index pattern, _it cannot be recovered_.
+
+[[index-patterns-api-delete-request]]
+==== Request
+
+`DELETE <kibana host>:<port>/api/index_patterns/index_pattern/<id>`
+
+`DELETE <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>`
+
+[[index-patterns-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.
+
+`id`::
+  (Required, string) The ID of an index pattern that you want to remove.
+
+[[index-patterns-api-delete-response-codes]]
+==== Response code
+
+`200`::
+  Indicates that index pattern is deleted. Returns an response empty body. 
+
+==== Example
+
+Delete an index pattern object with the `my-pattern` ID:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X DELETE api/index_patterns/index_pattern/my-pattern
+--------------------------------------------------
+// KIBANA

docs/api/index-patterns/get.asciidoc

@@ -0,0 +1,64 @@
+[[index-patterns-api-get]]
+=== Get index pattern API
+++++
+<titleabbrev>Get index pattern</titleabbrev>
+++++
+
+experimental[] Retrieve a single {kib} index pattern by ID.
+
+[[index-patterns-api-get-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/index_patterns/index_pattern/<id>`
+
+`GET <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>`
+
+[[index-patterns-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.
+
+`id`::
+(Required, string) The ID of the index pattern to retrieve.
+
+[[index-patterns-api-get-codes]]
+==== Response code
+
+`200`::
+Indicates a successful call.
+
+`404`::
+Index pattern with id `<id>` doesn't exist.
+
+[[index-patterns-api-get-example]]
+==== Example
+
+Retrieve the index pattern object with the `my-pattern` ID:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/index_patterns/index_pattern/my-pattern
+--------------------------------------------------
+// KIBANA
+
+The API returns an index pattern object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {
+        "id": "my-pattern",
+        "version": "...",
+        "title": "...",
+        "type": "...",
+        "timeFieldName": "...",
+        "sourceFilters": [],
+        "fields": {},
+        "typeMeta": {},
+        "fieldFormats": {},
+        "fieldAttrs": {},
+        "allowNoIndex: "..."
+    }
+}
+--------------------------------------------------

docs/api/index-patterns/update-fields.asciidoc

@@ -0,0 +1,100 @@
+[[index-patterns-fields-api-update]]
+=== Update index pattern fields API
+++++
+<titleabbrev>Update index pattern fields metadata</titleabbrev>
+++++
+
+experimental[] Update fields endpoint allows you to update fields presentation metadata, such as `count`,
+`customLabel`, and `format`. You can update multiple fields in one request. Updates
+are merged with persisted metadata. To remove existing metadata specify `null` as value.
+
+[[index-patterns-fields-api-update-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/index_patterns/index_pattern/<id>/fields`
+
+`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>/fields`
+
+[[index-patterns-fields-api-update-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.
+
+`id`::
+(Required, string) The ID of index pattern fields of which to update.
+
+[[index-patterns-fields-api-update-request-body]]
+==== Request body
+
+`fields`::
+(Required, object) fields update spec. See examples below.
+
+
+[[index-patterns-fields-api-update-errors-codes]]
+==== Response code
+
+`200`::
+Indicates a successful call.
+
+[[index-patterns-fields-api-update-example]]
+==== Examples
+
+Set popularity `count` for field `foo`:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/saved_objects/index-pattern/my-pattern/fields
+{
+    "fields": {
+        "foo": {
+            "count": 123
+        }
+    }
+}
+--------------------------------------------------
+// KIBANA
+
+Update multiple metadata fields in one request:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/saved_objects/index-pattern/my-pattern/fields
+{
+    "fields": {
+        "foo": {
+            "count": 123,
+            "customLabel": "Foo"
+        },
+        "bar": {
+            "customLabel": "Bar"
+        }
+    }
+}
+--------------------------------------------------
+// KIBANA
+
+Use `null` value to delete metadata:
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/saved_objects/index-pattern/my-pattern/fields
+{
+    "fields": {
+        "foo": {
+            "customLabel": null
+        }
+    }
+}
+--------------------------------------------------
+// KIBANA
+
+
+The endpoint returns the updated index pattern object:
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {
+
+    }
+}
+--------------------------------------------------