[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.
+
+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": {
+
+ }
+}
+--------------------------------------------------