|
1 | 1 | [[api]] |
2 | 2 | = REST API |
3 | 3 |
|
4 | | -[partintro] |
5 | | --- |
6 | 4 | Some {kib} features are provided via a REST API, which is ideal for creating an |
7 | 5 | integration with {kib}, or automating certain aspects of configuring and |
8 | 6 | deploying {kib}. |
9 | 7 |
|
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 |
12 | 11 |
|
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. |
15 | 13 |
|
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. |
19 | 15 |
|
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>>. |
24 | 17 |
|
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. |
28 | 22 |
|
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 | +-------------------------------------------- |
31 | 95 |
|
32 | | --- |
33 | 96 |
|
34 | | -include::{kib-repo-dir}/api/using-api.asciidoc[] |
35 | 97 | include::{kib-repo-dir}/api/features.asciidoc[] |
36 | 98 | include::{kib-repo-dir}/api/spaces-management.asciidoc[] |
37 | 99 | include::{kib-repo-dir}/api/role-management.asciidoc[] |
|
0 commit comments