mirror of
https://github.com/elastic/kibana.git
synced 2025-04-21 16:29:04 -04:00
75f2d0c714
In DevTools, if you go to run `kbn:/s/foo/api/MY_REQUEST` then IF default space you effectively run `KIBANA/s/foo/api/MY_REQUEST` BUT IF non-default space e.g. `admin` you end up running `KIBANA/s/admin/s/foo/api/MY_REQUEST` which is invalid. This is not pointed out in Dev Tools and since this page updated to the emphasize the DevTools example, this is tripping up more users who think it should work via this page. Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
109 lines
4 KiB
Text
109 lines
4 KiB
Text
[[api]]
|
|
= REST API
|
|
|
|
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}.
|
|
|
|
[float]
|
|
[[using-apis]]
|
|
== Using the APIs
|
|
|
|
Prepend any {kib} API endpoint with `kbn:` and send the request through <<console-kibana, Dev Tools > Console>>.
|
|
For example:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
`GET kbn:/api/index_management/indices`
|
|
--------------------------------------------------
|
|
|
|
Note: this will automatically prefix `s/{space_id}/` on the API request if ran from a non-default Kibana Space.
|
|
|
|
[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.
|
|
|
|
[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/features.asciidoc[]
|
|
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/data-views.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/cases.asciidoc[]
|
|
include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
|
|
include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
|
|
include::{kib-repo-dir}/api/machine-learning.asciidoc[]
|
|
include::{kib-repo-dir}/api/osquery-manager.asciidoc[]
|
|
include::{kib-repo-dir}/api/short-urls.asciidoc[]
|
|
include::{kib-repo-dir}/api/task-manager/health.asciidoc[]
|
|
include::{kib-repo-dir}/api/upgrade-assistant.asciidoc[]
|