Skip to content

Commit

Permalink
[Actions][Docs] Actions and Connectors API Docs (elastic#90974)
Browse files Browse the repository at this point in the history
* Stubbing out asciidocs

* wip

* Finishing connector API docs

* Cleanup

* Removing experimental label

* PR fixes

* PR fixes

* PR fixes
  • Loading branch information
ymao1 committed Feb 19, 2021
1 parent 0a8b494 commit d8cd5b5
Show file tree
Hide file tree
Showing 18 changed files with 455 additions and 0 deletions.
30 changes: 30 additions & 0 deletions docs/api/actions-and-connectors.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
[[actions-and-connectors-api]]
== Action and connector APIs

Manage Actions and Connectors.

The following action APIs are available:

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

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

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

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

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

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

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

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

include::actions-and-connectors/get.asciidoc[]
include::actions-and-connectors/get_all.asciidoc[]
include::actions-and-connectors/list.asciidoc[]
include::actions-and-connectors/create.asciidoc[]
include::actions-and-connectors/update.asciidoc[]
include::actions-and-connectors/execute.asciidoc[]
include::actions-and-connectors/delete.asciidoc[]
68 changes: 68 additions & 0 deletions docs/api/actions-and-connectors/create.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
[[actions-and-connectors-api-create]]
=== Create action API
++++
<titleabbrev>Create action API</titleabbrev>
++++

Creates an action.

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

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

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

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

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

`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>>.

`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>>.

[[actions-and-connectors-api-create-request-codes]]
==== Response code

`200`::
Indicates a successful call.

[[actions-and-connectors-api-create-example]]
==== Example

[source,sh]
--------------------------------------------------
$ curl -X POST api/actions/action -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
{
"name": "my-action",
"actionTypeId": ".index",
"config": {
"index": "test-index"
}
}'
--------------------------------------------------
// KIBANA

The API returns the following:

[source,sh]
--------------------------------------------------
{
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
"actionTypeId": ".index",
"name": "my-action",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"isPreconfigured": false
}
--------------------------------------------------
35 changes: 35 additions & 0 deletions docs/api/actions-and-connectors/delete.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
[[actions-and-connectors-api-delete]]
=== Delete action API
++++
<titleabbrev>Delete action API</titleabbrev>
++++

Deletes an action by ID.

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

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

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

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

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

[[actions-and-connectors-api-delete-response-codes]]
==== Response code

`200`::
Indicates a successful call.

==== Example

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

83 changes: 83 additions & 0 deletions docs/api/actions-and-connectors/execute.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
[[actions-and-connectors-api-execute]]
=== Execute action API
++++
<titleabbrev>Execute action API</titleabbrev>
++++

Executes an action by ID.

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

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

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

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

[[actions-and-connectors-api-execute-request-body]]
==== 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>>.

[[actions-and-connectors-api-execute-codes]]
==== Response code

`200`::
Indicates a successful call.

[[actions-and-connectors-api-execute-example]]
==== Example

[source,sh]
--------------------------------------------------
$ curl -X POST api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad/_execute -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
{
"params": {
"documents": [
{
"id": "test_doc_id",
"name": "test_doc_name",
"message": "hello, world"
}
]
}
}'
--------------------------------------------------
// KIBANA

The API returns the following:

[source,sh]
--------------------------------------------------
{
"status": "ok",
"data": {
"took": 197,
"errors": false,
"items": [
{
"index": {
"_index": "updated-index",
"_id": "iKyijHcBKCsmXNFrQe3T",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 201
}
}
]
},
"actionId": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad"
}
--------------------------------------------------
50 changes: 50 additions & 0 deletions docs/api/actions-and-connectors/get.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
[[actions-and-connectors-api-get]]
=== Get action API
++++
<titleabbrev>Get action API</titleabbrev>
++++

Retrieves an action by ID.

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

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

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

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

[[actions-and-connectors-api-get-codes]]
==== Response code

`200`::
Indicates a successful call.

[[actions-and-connectors-api-get-example]]
==== Example

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

The API returns the following:

[source,sh]
--------------------------------------------------
{
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
"actionTypeId": ".index",
"name": "my-action",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"isPreconfigured": false
}
--------------------------------------------------
52 changes: 52 additions & 0 deletions docs/api/actions-and-connectors/get_all.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
[[actions-and-connectors-api-get-all]]
=== Get all actions API
++++
<titleabbrev>Get all actions API</titleabbrev>
++++

Retrieves all actions.

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

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

[[actions-and-connectors-api-get-all-codes]]
==== Response code

`200`::
Indicates a successful call.

[[actions-and-connectors-api-get-all-example]]
==== Example

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

The API returns the following:

[source,sh]
--------------------------------------------------
[
{
"id": "preconfigured-mail-action",
"actionTypeId": ".email",
"name": "email: preconfigured-mail-action",
"isPreconfigured": true
},
{
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
"actionTypeId": ".index",
"name": "my-action",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"isPreconfigured": false
}
]
--------------------------------------------------
59 changes: 59 additions & 0 deletions docs/api/actions-and-connectors/list.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
[[actions-and-connectors-api-list]]
=== List action types API
++++
<titleabbrev>List all action types API</titleabbrev>
++++

Retrieves a list of all action types.

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

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

[[actions-and-connectors-api-list-codes]]
==== Response code

`200`::
Indicates a successful call.

[[actions-and-connectors-api-list-example]]
==== Example

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

The API returns the following:

[source,sh]
--------------------------------------------------
[
{
"id": ".email", <1>
"name": "Email", <2>
"minimumLicenseRequired": "gold", <3>
"enabled": false, <4>
"enabledInConfig": true, <5>
"enabledInLicense": false <6>
},
{
"id": ".index",
"name": "Index",
"minimumLicenseRequired": "basic",
"enabled": true,
"enabledInConfig": true,
"enabledInLicense": true
}
]
--------------------------------------------------


<1> `id` - The unique ID of the action type.
<2> `name` - The name of the action type.
<3> `minimumLicenseRequired` - The license required to use the action type.
<4> `enabled` - Specifies if the action type is enabled or disabled in {kib}.
<5> `enabledInConfig` - Specifies if the action type is enabled or enabled in the {kib} .yml file.
<6> `enabledInLicense` - Specifies if the action type is enabled or disabled in the license.
Loading

0 comments on commit d8cd5b5

Please sign in to comment.