Skip to content

Commit 55ef13f

Browse files
YulNaumenkoYulNaumenko
authored
fixed merge conflicts (#92723)
1 parent dc96c5c commit 55ef13f

2 files changed

Lines changed: 82 additions & 106 deletions

File tree

‎docs/api/using-api.asciidoc‎

Lines changed: 0 additions & 86 deletions
This file was deleted.

‎docs/user/api.asciidoc‎

Lines changed: 82 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,99 @@
11
[[api]]
22
= REST API
33

4-
[partintro]
5-
--
64
Some {kib} features are provided via a REST API, which is ideal for creating an
75
integration with {kib}, or automating certain aspects of configuring and
86
deploying {kib}.
97

10-
Each API is experimental and can include breaking changes in any version of
11-
{kib}, or might be entirely removed from {kib}.
8+
[float]
9+
[[using-apis]]
10+
== Using the APIs
1211

13-
////
14-
Each API has one of the following labels:
12+
Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols.
1513

16-
* *Stable* APIs should be safe to use extensively in production. Any breaking
17-
changes to these APIs should only occur in major versions and will be
18-
clearly documented in the breaking changes documentation for that release.
14+
It is recommended that you use HTTPs on port 5601 because it is more secure.
1915

20-
* *Beta* APIs are on track to become stable, permanent features of {kib}.
21-
Caution should be exercised in their use since it is possible we'd have to make
22-
a breaking change to these APIs in a minor version, but we'll avoid this
23-
wherever possible.
16+
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>>.
2417

25-
* *Experimental* APIs are just that - an experiment. An experimental API might
26-
have breaking changes in any version of {kib}, or it might even be removed
27-
entirely.
18+
[float]
19+
[[api-authentication]]
20+
=== Authentication
21+
The {kib} APIs support key- and token-based authentication.
2822

29-
If a label is missing from an API, it is considered `experimental`.
30-
////
23+
[float]
24+
[[token-api-authentication]]
25+
==== Token-based authentication
26+
27+
To use token-based authentication, you use the same username and password that you use to log into Elastic.
28+
In a given HTTP tool, and when available, you can select to use its 'Basic Authentication' option,
29+
which is where the username and password are stored in order to be passed as part of the call.
30+
31+
[float]
32+
[[key-authentication]]
33+
==== Key-based authentication
34+
35+
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.
36+
37+
For information about API keys, refer to <<api-keys,API keys>>.
38+
39+
[float]
40+
[[api-calls]]
41+
=== API calls
42+
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.
43+
44+
Calls to the API endpoints require different operations. To interact with the {kib} APIs, use the following operations:
45+
46+
* *GET* - Fetches the information.
47+
48+
* *POST* - Adds new information.
49+
50+
* *PUT* - Updates the existing information.
51+
52+
* *DELETE* - Removes the information.
53+
54+
For example, the following `curl` command exports a dashboard:
55+
56+
[source,sh]
57+
--------------------------------------------
58+
curl -X POST api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c
59+
--------------------------------------------
60+
// KIBANA
61+
62+
[float]
63+
[[api-request-headers]]
64+
=== Request headers
65+
66+
For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsrf` and `Content-Type` headers.
67+
68+
`kbn-xsrf: true`::
69+
By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
70+
71+
* The API endpoint uses the `GET` or `HEAD` operations
72+
* The path is allowed using the <<settings-xsrf-allowlist, `server.xsrf.allowlist`>> setting
73+
* XSRF protections are disabled using the <<settings-xsrf-disableProtection, `server.xsrf.disableProtection`>> setting
74+
75+
`Content-Type: application/json`::
76+
Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON.
77+
Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
78+
79+
Request header example:
80+
81+
[source,sh]
82+
--------------------------------------------
83+
curl -X POST \
84+
http://localhost:5601/api/spaces/space \
85+
-H 'Content-Type: application/json' \
86+
-H 'kbn-xsrf: true' \
87+
-d '{
88+
"id": "sales",
89+
"name": "Sales",
90+
"description": "This is your Sales Space!",
91+
"disabledFeatures": []
92+
}
93+
'
94+
--------------------------------------------
3195

32-
--
3396

34-
include::{kib-repo-dir}/api/using-api.asciidoc[]
3597
include::{kib-repo-dir}/api/features.asciidoc[]
3698
include::{kib-repo-dir}/api/spaces-management.asciidoc[]
3799
include::{kib-repo-dir}/api/role-management.asciidoc[]

0 commit comments

Comments
 (0)