[Docs] Index patterns REST API docs (#100549)

docs/api/index-patterns.asciidoc

@@ -0,0 +1,27 @@
+[[index-patterns-api]]
+== Index patterns APIs
+
+experimental[] Manage {kib} index patterns.
+
+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 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 patterns.
+
+[[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) Overrides an existing index pattern if an
+index pattern with the provided title already exists. The default is `false`.
+
+`refresh_fields`:: (Optional, boolean) Reloads index pattern fields after
+the index pattern is stored. The default is `false`.
+
+`index_pattern`:: (Required, object) The index pattern object. All fields are optional.
+
+[[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 the 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:
+
+[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 the 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 patterns.
+
+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 the index pattern you want to delete.
+
+[[index-patterns-api-delete-response-codes]]
+==== Response code
+
+`200`::
+  Indicates that index pattern is deleted. Returns an empty response 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 you want to retrieve.
+
+[[index-patterns-api-get-codes]]
+==== Response code
+
+`200`::
+Indicates a successful call.
+
+`404`::
+The specified index pattern and 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 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 the 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 the index pattern fields you want to update.
+
+[[index-patterns-fields-api-update-request-body]]
+==== Request body
+
+`fields`::
+(Required, object) the field object
+
+
+[[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": {
+
+    }
+}
+--------------------------------------------------

docs/api/index-patterns/update.asciidoc

@@ -0,0 +1,111 @@
+[[index-patterns-api-update]]
+=== Update index pattern API
+++++
+<titleabbrev>Update index pattern</titleabbrev>
+++++
+
+experimental[] Update part of an index pattern. Only the specified fields are updated in the
+index pattern. Unspecified fields stay as they are persisted.
+
+[[index-patterns-api-update-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/index_patterns/index_pattern/<id>`
+
+`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<id>`
+
+[[index-patterns-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 the index pattern you want to update.
+
+[[index-patterns-api-update-request-body]]
+==== Request body
+
+`refresh_fields`:: (Optional, boolean) Reloads the index pattern fields after
+the index pattern is updated. The default is `false`.
+
+`index_pattern`::
+  (Required, object) The index patterns fields you want to update.
++
+
+You can partially update the following fields:
+
+* `title`
+* `timeFieldName`
+* `fields`
+* `sourceFilters`
+* `fieldFormatMap`
+* `type`
+* `typeMeta`
+
+[[index-patterns-api-update-errors-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[index-patterns-api-update-example]]
+==== Examples
+
+Update a title of the `<my-pattern>` index pattern:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/saved_objects/index-pattern/my-pattern
+{
+  "index_pattern": {
+    "title": "some-other-pattern-*"
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+Customize the update behavior:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/saved_objects/index-pattern/my-pattern
+{
+  "refresh_fields": true,
+  "index_pattern": {
+    "fields": {}
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+
+All update fields are optional, but you can specify the following fields:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/saved_objects/index-pattern/my-pattern
+{
+  "index_pattern": {
+    "title": "...",
+    "timeFieldName": "...",
+    "sourceFilters": [],
+    "fieldFormats": {},
+    "type": "...",
+    "typeMeta": {},
+    "fields": {}
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+The API returns the updated index pattern object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {
+
+    }
+}
+--------------------------------------------------

docs/api/saved-objects.asciidoc

@@ -1,11 +1,13 @@
 [[saved-objects-api]]
 == Saved objects APIs
 
-Manage {kib} saved objects, including dashboards, visualizations, index patterns, and more.
+Manage {kib} saved objects, including dashboards, visualizations, and more.
 
 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.
 
+NOTE: For managing {kib} index patterns, use the <<index-patterns-api, index patterns API>>.
+
 The following saved objects APIs are available: 
 
 * <<saved-objects-api-get, Get object API>> to retrieve a single {kib} saved object by ID

docs/user/api.asciidoc

@@ -99,6 +99,7 @@ include::{kib-repo-dir}/api/spaces-management.asciidoc[]
 include::{kib-repo-dir}/api/role-management.asciidoc[]
 include::{kib-repo-dir}/api/session-management.asciidoc[]
 include::{kib-repo-dir}/api/saved-objects.asciidoc[]
+include::{kib-repo-dir}/api/index-patterns.asciidoc[]
 include::{kib-repo-dir}/api/alerting.asciidoc[]
 include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[]
 include::{kib-repo-dir}/api/dashboard-api.asciidoc[]