[Docs] Changed REST API intro page with removing experimental definition for all APIs. (#92539)
* [Docs] Changed REST API intro page with removing experimental definition for all APIs * fixed ci * fixed ci
This commit is contained in:
Yuliia Naumenko
GitHub
parent
614c6c6853
commit
fb96b9c755
|
|
@ -1,86 +0,0 @@
|
|||
[[using-api]]
|
||||
== Using the APIs
|
||||
|
||||
Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols.
|
||||
|
||||
It is recommended that you use HTTPs on port 5601 because it is more secure.
|
||||
|
||||
NOTE: The {kib} Console supports only Elasticsearch APIs. You are unable to interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to <<console-kibana,Console>>.
|
||||
|
||||
[float]
|
||||
[[api-authentication]]
|
||||
=== Authentication
|
||||
The {kib} APIs support key- and token-based authentication.
|
||||
|
||||
[float]
|
||||
[[token-api-authentication]]
|
||||
==== Token-based authentication
|
||||
|
||||
To use token-based authentication, you use the same username and password that you use to log into Elastic.
|
||||
In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option,
|
||||
which is where the username and password are stored in order to be passed as part of the call.
|
||||
|
||||
[float]
|
||||
[[key-authentication]]
|
||||
==== Key-based authentication
|
||||
|
||||
To use key-based authentication, you create an API key using the Elastic Console, then specify the key in the header of your API calls.
|
||||
|
||||
For information about API keys, refer to <<api-keys,API keys>>.
|
||||
|
||||
[float]
|
||||
[[api-calls]]
|
||||
=== API calls
|
||||
API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for {kib} to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.
|
||||
|
||||
Calls to the API endpoints require different operations. To interact with the {kib} APIs, use the following operations:
|
||||
|
||||
* *GET* - Fetches the information.
|
||||
|
||||
* *POST* - Adds new information.
|
||||
|
||||
* *PUT* - Updates the existing information.
|
||||
|
||||
* *DELETE* - Removes the information.
|
||||
|
||||
For example, the following `curl` command exports a dashboard:
|
||||
|
||||
[source,sh]
|
||||
--
|
||||
curl -X POST api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c
|
||||
--
|
||||
// KIBANA
|
||||
|
||||
[float]
|
||||
[[api-request-headers]]
|
||||
=== Request headers
|
||||
|
||||
For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsrf` and `Content-Type` headers.
|
||||
|
||||
`kbn-xsrf: true`::
|
||||
By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
|
||||
|
||||
* The API endpoint uses the `GET` or `HEAD` operations
|
||||
* The path is allowed using the <<settings-xsrf-allowlist, `server.xsrf.allowlist`>> setting
|
||||
* XSRF protections are disabled using the <<settings-xsrf-disableProtection, `server.xsrf.disableProtection`>> setting
|
||||
|
||||
`Content-Type: application/json`::
|
||||
Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON.
|
||||
Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
|
||||
|
||||
Request header example:
|
||||
|
||||
[source,sh]
|
||||
--
|
||||
curl -X POST \
|
||||
http://localhost:5601/api/spaces/space \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'kbn-xsrf: true' \
|
||||
-d '{
|
||||
"id": "sales",
|
||||
"name": "Sales",
|
||||
"description": "This is your Sales Space!",
|
||||
"disabledFeatures": []
|
||||
}
|
||||
'
|
||||
--
|
||||
|
|
@ -1,37 +1,99 @@
|
|||
[[api]]
|
||||
= REST API
|
||||
|
||||
[partintro]
|
||||
--
|
||||
Some {kib} features are provided via a REST API, which is ideal for creating an
|
||||
integration with {kib}, or automating certain aspects of configuring and
|
||||
deploying {kib}.
|
||||
|
||||
Each API is experimental and can include breaking changes in any version of
|
||||
{kib}, or might be entirely removed from {kib}.
|
||||
[float]
|
||||
[[using-apis]]
|
||||
== Using the APIs
|
||||
|
||||
////
|
||||
Each API has one of the following labels:
|
||||
Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols.
|
||||
|
||||
* *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.
|
||||
It is recommended that you use HTTPs on port 5601 because it is more secure.
|
||||
|
||||
* *Beta* APIs are on track to become stable, permanent features of {kib}.
|
||||
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.
|
||||
NOTE: The {kib} Console supports only Elasticsearch APIs. You are unable to interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to <<console-kibana,Console>>.
|
||||
|
||||
* *Experimental* APIs are just that - an experiment. An experimental API might
|
||||
have breaking changes in any version of {kib}, or it might even be removed
|
||||
entirely.
|
||||
[float]
|
||||
[[api-authentication]]
|
||||
=== Authentication
|
||||
The {kib} APIs support key- and token-based authentication.
|
||||
|
||||
If a label is missing from an API, it is considered `experimental`.
|
||||
////
|
||||
[float]
|
||||
[[token-api-authentication]]
|
||||
==== Token-based authentication
|
||||
|
||||
To use token-based authentication, you use the same username and password that you use to log into Elastic.
|
||||
In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option,
|
||||
which is where the username and password are stored in order to be passed as part of the call.
|
||||
|
||||
[float]
|
||||
[[key-authentication]]
|
||||
==== Key-based authentication
|
||||
|
||||
To use key-based authentication, you create an API key using the Elastic Console, then specify the key in the header of your API calls.
|
||||
|
||||
For information about API keys, refer to <<api-keys,API keys>>.
|
||||
|
||||
[float]
|
||||
[[api-calls]]
|
||||
=== API calls
|
||||
API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for {kib} to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.
|
||||
|
||||
Calls to the API endpoints require different operations. To interact with the {kib} APIs, use the following operations:
|
||||
|
||||
* *GET* - Fetches the information.
|
||||
|
||||
* *POST* - Adds new information.
|
||||
|
||||
* *PUT* - Updates the existing information.
|
||||
|
||||
* *DELETE* - Removes the information.
|
||||
|
||||
For example, the following `curl` command exports a dashboard:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------
|
||||
curl -X POST api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c
|
||||
--------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
[float]
|
||||
[[api-request-headers]]
|
||||
=== Request headers
|
||||
|
||||
For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsrf` and `Content-Type` headers.
|
||||
|
||||
`kbn-xsrf: true`::
|
||||
By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
|
||||
|
||||
* The API endpoint uses the `GET` or `HEAD` operations
|
||||
* The path is allowed using the <<settings-xsrf-allowlist, `server.xsrf.allowlist`>> setting
|
||||
* XSRF protections are disabled using the <<settings-xsrf-disableProtection, `server.xsrf.disableProtection`>> setting
|
||||
|
||||
`Content-Type: application/json`::
|
||||
Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON.
|
||||
Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
|
||||
|
||||
Request header example:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------
|
||||
curl -X POST \
|
||||
http://localhost:5601/api/spaces/space \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'kbn-xsrf: true' \
|
||||
-d '{
|
||||
"id": "sales",
|
||||
"name": "Sales",
|
||||
"description": "This is your Sales Space!",
|
||||
"disabledFeatures": []
|
||||
}
|
||||
'
|
||||
--------------------------------------------
|
||||
|
||||
--
|
||||
|
||||
include::{kib-repo-dir}/api/using-api.asciidoc[]
|
||||
include::{kib-repo-dir}/api/features.asciidoc[]
|
||||
include::{kib-repo-dir}/api/spaces-management.asciidoc[]
|
||||
include::{kib-repo-dir}/api/role-management.asciidoc[]
|
||||
|
|
|
|||
Loading…
Reference in a new issue