@@ -15,8 +15,39 @@ Some APM app features are provided via a REST API:
1515[[apm-api-example]]
1616=== Using the APIs
1717
18- Users interacting with APM APIs must have <<apm-app-api-user,sufficient privileges>>.
19- In addition, there are request headers to be aware of, like `kbn-xsrf: true`, and `Content-Type: applicaton/json`.
18+ // The following content is reused throughout the API docs
19+ // tag::using-the-APIs[]
20+ Interact with APM APIs using cURL or another API tool.
21+ All APM APIs are Kibana APIs, not Elasticsearch APIs;
22+ because of this, the Kibana dev tools console cannot be used to interact with APM APIs.
23+
24+ For all APM APIs, you must use a request header.
25+ Supported headers are `Authorization`, `kbn-xsrf`, and `Content-Type`.
26+
27+ `Authorization: ApiKey {credentials}`::
28+ Kibana supports token-based authentication with the Elasticsearch API key service.
29+ The API key returned by the {ref}/security-api-create-api-key.html[Elasticsearch create API key API]
30+ can be used by sending a request with an `Authorization` header that has a value of `ApiKey` followed by the `{credentials}`,
31+ where `{credentials}` is the base64 encoding of `id` and `api_key` joined by a colon.
32+ +
33+ Alternatively, you can create a user and use their username and password to authenticate API access: `-u $USER:$PASSWORD`.
34+ +
35+ Whether using `Authorization: ApiKey {credentials}`, or `-u $USER:$PASSWORD`,
36+ users interacting with APM APIs must have <<apm-app-api-user,sufficient privileges>>.
37+
38+ `kbn-xsrf: true`::
39+ By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
40+
41+ * The API endpoint uses the `GET` or `HEAD` operations
42+ * The path is whitelisted using the <<settings, `server.xsrf.whitelist`>> setting
43+ * XSRF protections are disabled using the `server.xsrf.disableProtection` setting
44+
45+ `Content-Type: application/json`::
46+ Applicable only when you send a payload in the API request.
47+ {kib} API requests and responses use JSON.
48+ Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
49+ // end::using-the-APIs[]
50+
2051Here's an example CURL request that adds an annotation to the APM app:
2152
2253[source,curl]
@@ -38,9 +69,6 @@ curl -X POST \
3869 }'
3970----
4071
41- The Kibana <<api,REST API reference>> provides additional information on how to use Kibana APIs,
42- required request headers, and token-based authentication options.
43-
4472////
4573*******************************************************
4674////
@@ -59,7 +87,15 @@ The following Agent configuration APIs are available:
5987* <<apm-list-config>> to list all Agent configurations.
6088* <<apm-search-config>> to search for an Agent configuration.
6189
62- See <<apm-app-api-config-manager>> for information on the privileges required to use this API endpoint.
90+ [float]
91+ [[use-agent-config-api]]
92+ ==== How to use APM APIs
93+
94+ .Expand for required headers, privileges, and usage details
95+ [%collapsible%closed]
96+ ======
97+ include::api.asciidoc[tag=using-the-APIs]
98+ ======
6399
64100////
65101*******************************************************
@@ -100,7 +136,7 @@ See <<apm-app-api-config-manager>> for information on the privileges required to
100136[[apm-update-config-example]]
101137===== Example
102138
103- [source,console ]
139+ [source,curl ]
104140--------------------------------------------------
105141PUT /api/apm/settings/agent-configuration
106142{
@@ -150,7 +186,7 @@ PUT /api/apm/settings/agent-configuration
150186[[apm-delete-config-example]]
151187===== Example
152188
153- [source,console ]
189+ [source,curl ]
154190--------------------------------------------------
155191DELETE /api/apm/settings/agent-configuration
156192{
@@ -228,7 +264,7 @@ DELETE /api/apm/settings/agent-configuration
228264[[apm-list-config-example]]
229265===== Example
230266
231- [source,console ]
267+ [source,curl ]
232268--------------------------------------------------
233269GET /api/apm/settings/agent-configuration
234270--------------------------------------------------
@@ -293,7 +329,7 @@ GET /api/apm/settings/agent-configuration
293329[[apm-search-config-example]]
294330===== Example
295331
296- [source,console ]
332+ [source,curl ]
297333--------------------------------------------------
298334POST /api/apm/settings/agent-configuration/search
299335{
@@ -317,17 +353,25 @@ POST /api/apm/settings/agent-configuration/search
317353The Annotation API allows you to annotate visualizations in the APM app with significant events, like deployments,
318354allowing you to easily see how these events are impacting the performance of your existing applications.
319355
356+ By default, annotations are stored in a newly created `observability-annotations` index.
357+ The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`.
358+
320359The following APIs are available:
321360
322361* <<apm-annotation-create>> to create an annotation for APM.
323362// * <<obs-annotation-create>> POST /api/observability/annotation
324363// * <<obs-annotation-get>> GET /api/observability/annotation/:id
325364// * <<obs-annotation-delete>> DELETE /api/observability/annotation/:id
326365
327- By default, annotations are stored in a newly created `observability-annotations` index.
328- The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`.
366+ [float]
367+ [[use-annotation-api]]
368+ ==== How to use APM APIs
329369
330- See <<apm-app-api-annotation-manager>> for information on the privileges required to use this API endpoint.
370+ .Expand for required headers, privileges, and usage details
371+ [%collapsible%closed]
372+ ======
373+ include::api.asciidoc[tag=using-the-APIs]
374+ ======
331375
332376////
333377*******************************************************
@@ -374,19 +418,20 @@ While you can add additional tags, you cannot remove the `apm` tag.
374418
375419The following example creates an annotation for a service named `opbeans-java`.
376420
377- [source,console ]
421+ [source,curl ]
378422--------------------------------------------------
379- POST /api/apm/services/opbeans-java/annotation
380- {
381- "@timestamp": "2020-05-08T10:31:30.452Z",
382- "service": {
383- "version": "1.2"
384- },
385- "message": "Deployment 1.2",
386- "tags": [
387- "elastic.co", "customer"
388- ]
389- }
423+ curl -X POST \
424+ http://localhost:5601/api/apm/services/opbeans-java/annotation \
425+ -H 'Content-Type: application/json' \
426+ -H 'kbn-xsrf: true' \
427+ -H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
428+ -d '{
429+ "@timestamp": "2020-05-08T10:31:30.452Z",
430+ "service": {
431+ "version": "1.2"
432+ },
433+ "message": "Deployment 1.2"
434+ }'
390435--------------------------------------------------
391436
392437[[apm-annotation-config-body]]
0 commit comments