From fee942d7573659f47da681604657a2935952c84d Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 24 Feb 2021 14:38:19 -0800 Subject: [PATCH] fixed merge conflicts (#92726) --- docs/api/using-api.asciidoc | 86 ------------------------------ docs/user/api.asciidoc | 102 +++++++++++++++++++++++++++++------- 2 files changed, 82 insertions(+), 106 deletions(-) delete mode 100644 docs/api/using-api.asciidoc diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc deleted file mode 100644 index c32b8d69d3c0d5..00000000000000 --- a/docs/api/using-api.asciidoc +++ /dev/null @@ -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 <>. - -[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 <>. - -[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 <> setting -* XSRF protections are disabled using the <> 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": [] -} -' --- diff --git a/docs/user/api.asciidoc b/docs/user/api.asciidoc index 9916ab42186dc6..459dbbdd34b279 100644 --- a/docs/user/api.asciidoc +++ b/docs/user/api.asciidoc @@ -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 <>. -* *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 <>. + +[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 <> setting +* XSRF protections are disabled using the <> 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[]