Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Alerting] adds Connectors APIs and deprecates old Actions APIs as per the new Alerting terminology #92451

Merged
merged 27 commits into from
Mar 5, 2021
Merged

[Alerting] adds Connectors APIs and deprecates old Actions APIs as per the new Alerting terminology #92451

Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
47594cb
moved legacy actions api to legacy folder
gmmorris Feb 23, 2021
e4cac15
introduced connector create api
gmmorris Feb 25, 2021
14e9f1f
added new delete route
gmmorris Mar 1, 2021
4ec8d3a
added new execute and get_all
gmmorris Mar 1, 2021
1caa038
introduced all connector APIs
gmmorris Mar 2, 2021
abf36db
renamed action to connector in Apis
gmmorris Mar 2, 2021
a1ab01d
comment on camel case type
gmmorris Mar 2, 2021
234cdfc
fixed va
gmmorris Mar 2, 2021
88098e3
Merge branch 'master' into actions/terminology-api
gmmorris Mar 2, 2021
c7f9b0d
updated docs
gmmorris Mar 3, 2021
098b766
legacy title
gmmorris Mar 3, 2021
f71f42f
corrected APIs
gmmorris Mar 3, 2021
6f2333d
legacy links
gmmorris Mar 3, 2021
020385a
added linik to deprecatred APIs
gmmorris Mar 3, 2021
bb283bf
added linik to deprecatred APIs from index
gmmorris Mar 3, 2021
c750557
moved legacy apis down one level
gmmorris Mar 3, 2021
d005de3
Apply suggestions from code review
gmmorris Mar 4, 2021
97e2549
renamed route file for connectorTypesRoute
gmmorris Mar 4, 2021
71c8965
Merge branch 'actions/terminology-api' of github.com:gmmorris/kibana …
gmmorris Mar 4, 2021
923cd1e
define legacy route
gmmorris Mar 4, 2021
62a21e9
Update docs/api/actions-and-connectors/legacy/index.asciidoc
gmmorris Mar 4, 2021
55ff443
Merge branch 'master' into actions/terminology-api
gmmorris Mar 4, 2021
3a87a7d
Merge branch 'actions/terminology-api' of github.com:gmmorris/kibana …
gmmorris Mar 4, 2021
4b20afb
Merge branch 'master' into actions/terminology-api
kibanamachine Mar 4, 2021
3deed12
api docs
gmmorris Mar 4, 2021
c9d7e0e
Merge branch 'actions/terminology-api' of github.com:gmmorris/kibana …
gmmorris Mar 4, 2021
822d988
Merge branch 'master' into actions/terminology-api
gmmorris Mar 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions docs/api/actions-and-connectors.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,23 @@

Manage Actions and Connectors.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meta comment: I wonder if this is time to remove "Actions and Connectors" confusion. Since they are the same, we could call them "Connectors"? ex: "Manage Connectors" (+folder / file names).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are they the same though?
We'll still use action to refer to the execution of something by using a connector, right?
Especially one we support multiple actions per connector...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll still use action to refer to the execution of something by using a connector, right?

Correct but we only have the concept of actions on the side of the alert now, no?

I asked myself: "Is there any docs in the actions and connectors page the user can read to learn more about actions?"


The following action APIs are available:
The following connector APIs are available:

* <<actions-and-connectors-api-get, Get action API>> to retrieve a single action by ID
* <<actions-and-connectors-api-get, Get connector API>> to retrieve a single connector by ID

* <<actions-and-connectors-api-get-all, Get all actions API>> to retrieve all actions
* <<actions-and-connectors-api-get-all, Get all connectors API>> to retrieve all connectors

* <<actions-and-connectors-api-list, List all action types API>> to retrieve a list of all action types
* <<actions-and-connectors-api-list, List all connector types API>> to retrieve a list of all connector types

* <<actions-and-connectors-api-create, Create action API>> to create actions
* <<actions-and-connectors-api-create, Create connector API>> to create connectors

* <<actions-and-connectors-api-update, Update action API>> to update the attributes for an existing action
* <<actions-and-connectors-api-update, Update connector API>> to update the attributes for an existing connector

* <<actions-and-connectors-api-execute, Execute action API>> to execute an action by ID
* <<actions-and-connectors-api-execute, Execute connector API>> to execute a connector by ID

* <<actions-and-connectors-api-delete, Delete action API>> to delete an action by ID
* <<actions-and-connectors-api-delete, Delete connector API>> to delete a connector by ID

For deprecated APIs, refer to <<actions-and-connectors-legacy-apis>>.

For information about the actions and connectors that {kib} supports, refer to <<action-types,Action and connector types>>.

Expand All @@ -28,3 +30,11 @@ include::actions-and-connectors/create.asciidoc[]
include::actions-and-connectors/update.asciidoc[]
include::actions-and-connectors/execute.asciidoc[]
include::actions-and-connectors/delete.asciidoc[]
include::actions-and-connectors/legacy/index.asciidoc[]
include::actions-and-connectors/legacy/get.asciidoc[]
include::actions-and-connectors/legacy/get_all.asciidoc[]
include::actions-and-connectors/legacy/list.asciidoc[]
include::actions-and-connectors/legacy/create.asciidoc[]
include::actions-and-connectors/legacy/update.asciidoc[]
include::actions-and-connectors/legacy/execute.asciidoc[]
include::actions-and-connectors/legacy/delete.asciidoc[]
36 changes: 18 additions & 18 deletions docs/api/actions-and-connectors/create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
[[actions-and-connectors-api-create]]
=== Create action API
=== Create connector API
++++
<titleabbrev>Create action API</titleabbrev>
<titleabbrev>Create connector API</titleabbrev>
++++

Creates an action.
Creates a connector.

[[actions-and-connectors-api-create-request]]
==== Request

`POST <kibana host>:<port>/api/actions/action`
`POST <kibana host>:<port>/api/actions/connector`

`POST <kibana host>:<port>/s/<space_id>/api/actions/action`
`POST <kibana host>:<port>/s/<space_id>/api/actions/connector`

[[actions-and-connectors-api-create-path-params]]
==== Path parameters
Expand All @@ -23,18 +23,18 @@ Creates an action.
==== Request body

`name`::
(Required, string) The display name for the action.
(Required, string) The display name for the connector.

`actionTypeId`::
(Required, string) The action type ID for the action.
`connector_type_id`::
(Required, string) The connector type ID for the connector.

`config`::
(Required, object) The configuration for the action. Configuration properties vary depending on
the action type. For information about the configuration properties, refer to <<action-types,Action and connector types>>.
(Required, object) The configuration for the connector. Configuration properties vary depending on
the connector type. For information about the configuration properties, refer to <<action-types,Action and connector types>>.

`secrets`::
(Required, object) The secrets configuration for the action. Secrets configuration properties vary
depending on the action type. For information about the secrets configuration properties, refer to <<action-types,Action and connector types>>.
(Required, object) The secrets configuration for the connector. Secrets configuration properties vary
depending on the connector type. For information about the secrets configuration properties, refer to <<action-types,Action and connector types>>.
+
WARNING: Remember these values. You must provide them each time you call the <<actions-and-connectors-api-update, update>> API.

Expand All @@ -49,10 +49,10 @@ WARNING: Remember these values. You must provide them each time you call the <<a

[source,sh]
--------------------------------------------------
$ curl -X POST api/actions/action -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
$ curl -X POST api/actions/connector -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
{
"name": "my-action",
"actionTypeId": ".index",
"name": "my-connector",
"connector_type_id": ".index",
"config": {
"index": "test-index"
}
Expand All @@ -66,13 +66,13 @@ The API returns the following:
--------------------------------------------------
{
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
"actionTypeId": ".index",
"name": "my-action",
"connector_type_id": ".index",
"name": "my-connector",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"isPreconfigured": false
"is_preconfigured": false
}
--------------------------------------------------
16 changes: 8 additions & 8 deletions docs/api/actions-and-connectors/delete.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
[[actions-and-connectors-api-delete]]
=== Delete action API
=== Delete connector API
++++
<titleabbrev>Delete action API</titleabbrev>
<titleabbrev>Delete connector API</titleabbrev>
++++

Deletes an action by ID.
Deletes an connector by ID.

WARNING: When you delete an action, _it cannot be recovered_.
WARNING: When you delete a connector, _it cannot be recovered_.

[[actions-and-connectors-api-delete-request]]
==== Request

`DELETE <kibana host>:<port>/api/actions/action/<id>`
`DELETE <kibana host>:<port>/api/actions/connector/<id>`

`DELETE <kibana host>:<port>/s/<space_id>/api/actions/action/<id>`
`DELETE <kibana host>:<port>/s/<space_id>/api/actions/connector/<id>`

[[actions-and-connectors-api-delete-path-params]]
==== Path parameters

`id`::
(Required, string) The ID of the action.
(Required, string) The ID of the connector.

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
Expand All @@ -34,6 +34,6 @@ WARNING: When you delete an action, _it cannot be recovered_.

[source,sh]
--------------------------------------------------
$ curl -X DELETE api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad
$ curl -X DELETE api/actions/connector/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad
--------------------------------------------------
// KIBANA
20 changes: 10 additions & 10 deletions docs/api/actions-and-connectors/execute.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
[[actions-and-connectors-api-execute]]
=== Execute action API
=== Execute connector API
++++
<titleabbrev>Execute action API</titleabbrev>
<titleabbrev>Execute connector API</titleabbrev>
++++

Executes an action by ID.
Executes a connector by ID.

[[actions-and-connectors-api-execute-request]]
==== Request

`POST <kibana host>:<port>/api/actions/action/<id>/_execute`
`POST <kibana host>:<port>/api/actions/connector/<id>/_execute`

`POST <kibana host>:<port>/s/<space_id>/api/actions/action/<id>/_execute`
`POST <kibana host>:<port>/s/<space_id>/api/actions/connector/<id>/_execute`

[[actions-and-connectors-api-execute-params]]
==== Path parameters

`id`::
(Required, string) The ID of the action.
(Required, string) The ID of the connector.

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
Expand All @@ -26,8 +26,8 @@ Executes an action by ID.
==== Request body

`params`::
(Required, object) The parameters of the action. Parameter properties vary depending on
the action type. For information about the parameter properties, refer to <<action-types,Action and connector types>>.
(Required, object) The parameters of the connector. Parameter properties vary depending on
the connector type. For information about the parameter properties, refer to <<action-types,Action and connector types>>.

[[actions-and-connectors-api-execute-codes]]
==== Response code
Expand All @@ -40,7 +40,7 @@ Executes an action by ID.

[source,sh]
--------------------------------------------------
$ curl -X POST api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad/_execute -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
$ curl -X POST api/actions/connector/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad/_execute -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
{
"params": {
"documents": [
Expand Down Expand Up @@ -83,6 +83,6 @@ The API returns the following:
}
]
},
"actionId": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad"
"connector_id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad"
}
--------------------------------------------------
20 changes: 10 additions & 10 deletions docs/api/actions-and-connectors/get.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
[[actions-and-connectors-api-get]]
=== Get action API
=== Get connector API
++++
<titleabbrev>Get action API</titleabbrev>
<titleabbrev>Get connector API</titleabbrev>
++++

Retrieves an action by ID.
Retrieves a connector by ID.

[[actions-and-connectors-api-get-request]]
==== Request

`GET <kibana host>:<port>/api/actions/action/<id>`
`GET <kibana host>:<port>/api/actions/connector/<id>`

`GET <kibana host>:<port>/s/<space_id>/api/actions/action/<id>`
`GET <kibana host>:<port>/s/<space_id>/api/actions/connector/<id>`

[[actions-and-connectors-api-get-params]]
==== Path parameters

`id`::
(Required, string) The ID of the action.
(Required, string) The ID of the connector.

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
Expand All @@ -33,7 +33,7 @@ Retrieves an action by ID.

[source,sh]
--------------------------------------------------
$ curl -X GET api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad
$ curl -X GET api/actions/connector/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad
--------------------------------------------------
// KIBANA

Expand All @@ -43,13 +43,13 @@ The API returns the following:
--------------------------------------------------
{
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
"actionTypeId": ".index",
"name": "my-action",
"connector_type_id": ".index",
"name": "my-connector",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"isPreconfigured": false
"is_preconfigured": false
}
--------------------------------------------------
24 changes: 13 additions & 11 deletions docs/api/actions-and-connectors/get_all.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@
<titleabbrev>Get all actions API</titleabbrev>
++++

Retrieves all actions.
Retrieves all connectors.

[[actions-and-connectors-api-get-all-request]]
==== Request

`GET <kibana host>:<port>/api/actions`
`GET <kibana host>:<port>/api/actions/connectors`

`GET <kibana host>:<port>/s/<space_id>/api/actions`
`GET <kibana host>:<port>/s/<space_id>/api/actions/connectors`

[[actions-and-connectors-api-get-all-path-params]]
==== Path parameters
Expand All @@ -30,7 +30,7 @@ Retrieves all actions.

[source,sh]
--------------------------------------------------
$ curl -X GET api/actions
$ curl -X GET api/actions/connectors
--------------------------------------------------
// KIBANA

Expand All @@ -40,21 +40,23 @@ The API returns the following:
--------------------------------------------------
[
{
"id": "preconfigured-mail-action",
"actionTypeId": ".email",
"name": "email: preconfigured-mail-action",
"isPreconfigured": true
"id": "preconfigured-mail-connector",
"connector_type_id": ".email",
"name": "email: preconfigured-mail-connector",
"is_preconfigured": true,
"referenced_by_count": 1
},
{
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
"actionTypeId": ".index",
"name": "my-action",
"connector_type_id": ".index",
"name": "my-connector",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"isPreconfigured": false
"is_preconfigured": false,
"referenced_by_count": 3
}
]
--------------------------------------------------
Loading