Commit 5ddec108 authored by Nils Bandener's avatar Nils Bandener
Browse files

Updated Signals REST API docs to the new tenant specification scheme

parent 1833ae68
......@@ -21,11 +21,11 @@ description:
## Endpoint
```
PUT /_signals/watch/{watch_id}/_ack
PUT /_signals/watch/{tenant_id}/{watch_id}/_ack
```
```
PUT /_signals/watch/{watch_id}/_ack/{action_id}
PUT /_signals/watch/{tenant_id}/{watch_id}/_ack/{action_id}
```
These endpoints can be used to acknowledge actions performed by watches. By acknowledging actions, you can temporarily suppress further executions of these actions.
......@@ -35,6 +35,8 @@ When an action is acknowledged, its checks will be still executed on schedule. T
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
**{watch_id}** The id of the watch containing the action to be acknowledged. Required.
**{action_id}** The id of the action to be acknowledged. Optional. If not specified, all actions of the watch will be acknowledged.
......@@ -57,16 +59,10 @@ The user does not have the permission to acknowledge watches for the currently s
A watch with the given id does not exist for the current tenant.
The status 404 is also returned if the tenant specified by the `sg_tenant` request header does not exist.
### 412 Precondition Failed
The specified action was not executed during its last scheduled run. Thus, it cannot be acknowledged.
## Multi Tenancy
The watch REST API is tenant-aware. Each Signals tenant has its own separate set of watches. The HTTP request header `sg_tenant` can be used to specify the tenant to be used. If the header is absent, the default tenant is used.
## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/ack` for the currently selected tenant.
......@@ -79,7 +75,7 @@ This permission is included in the following [built-in action groups](security_p
```
PUT /_signals/watch/bad_weather/_ack/email
PUT /_signals/watch/_main/bad_weather/_ack/email
```
**Response**
......
......@@ -20,17 +20,19 @@ description:
## Endpoint
```
PUT /_signals/watch/{watch_id}/_activate
PUT /_signals/watch/{tenant_id}/{watch_id}/_activate
```
```
PUT /_signals/watch/{watch_id}/_deactivate
PUT /_signals/watch/{tenant_id}/{watch_id}/_deactivate
```
These endpoints can be used to activate and deactivate watches. Inactive watches are not automatically executed.
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
**{watch_id}** The id of the watch to be activated or deactivated. Required.
## Request Body
......@@ -51,13 +53,6 @@ The user does not have the permission to activate or deactivate watches for the
A watch with the given id does not exist for the current tenant.
The status 404 is also returned if the tenant specified by the `sg_tenant` request header does not exist.
## Multi Tenancy
The watch REST API is tenant-aware. Each Signals tenant has its own separate set of watches. The HTTP request header `sg_tenant` can be used to specify the tenant to be used. If the header is absent, the default tenant is used.
## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/activate_deactivate` for the currently selected tenant.
......@@ -73,7 +68,7 @@ This permission is included in the following [built-in action groups](security_p
### Basic
```
PUT /_signals/watch/bad_weather/_deactivate
PUT /_signals/watch/_main/bad_weather/_deactivate
```
**Response**
......
......@@ -21,14 +21,16 @@ description:
## Endpoint
```
DELETE /_signals/watch/{watch_id}
DELETE /_signals/watch/{tenant_id}/{watch_id}
```
Deletes the watch identified by the `{watch_id}` path parameter.
Deletes the specified watch.
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
**{watch_id}** The id of the watch to be deleted. Required.
## Responses
......@@ -45,13 +47,6 @@ The user does not have the permission to delete watches for the currently select
A watch with the given id does not exist for the current tenant.
The status 404 is also returned if the tenant specified by the `sg_tenant` request header does not exist.
## Multi Tenancy
The watch REST API is tenant-aware. Each Signals tenant has its own separate set of watches. The HTTP request header `sg_tenant` can be used to specify the tenant to be used. If the header is absent, the default tenant is used.
## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/delete` for the currently selected tenant.
......@@ -64,7 +59,7 @@ This permission is included in the following [built-in action groups](security_p
## Examples
```
DELETE /_signals/watch/bad_weather
DELETE /_signals/watch/_main/bad_weather
```
......
......@@ -21,17 +21,19 @@ description:
## Endpoint
```
POST /_signals/watch/_execute
POST /_signals/watch/{tenant_id}/_execute
```
```
POST /_signals/watch/{watch_id}/_execute
POST /_signals/watch/{tenant_id}/{watch_id}/_execute
```
Immediately executes a watch and returns status information in the HTTP response. The watch can be specified in the request body. Alternatively, the watch to be executed can be specified by y the `{watch_id}` path parameter.
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
**{watch_id}** The id of the watch to be executed. Optional. If not specified, the watch needs to be specified in the request body.
## Request Body
......@@ -103,8 +105,6 @@ The user does not have the permission to execute watches for the currently selec
A watch with the given id does not exist for the selected tenant.
The status 404 is also returned if the tenant specified by the `sg_tenant` request header does not exist.
### 415 Unsupported Media Type
The watch was not encoded as JSON document. Watches need to be sent using the media type application/json.
......@@ -127,7 +127,7 @@ This permission is included in the following [built-in action groups](security_p
### Basic
```
POST /_signals/watch/bad_weather/_execute
POST /_signals/watch/_main/bad_weather/_execute
```
......@@ -139,7 +139,7 @@ POST /_signals/watch/bad_weather/_execute
```json
{
"tenant": "main",
"tenant": "_main",
"watch_id": "bad_weather",
"status": {
"code": "ACTION_TRIGGERED",
......@@ -183,7 +183,7 @@ POST /_signals/watch/bad_weather/_execute
### Execution Error
```
POST /_signals/watch/bad_weather/_execute
POST /_signals/_main/watch/bad_weather/_execute
```
**Response**
......@@ -194,7 +194,7 @@ POST /_signals/watch/bad_weather/_execute
```json
{
"tenant": "main",
"tenant": "_main",
"watch_id": "bad_weather",
"status": {
"code": "EXECUTION_FAILED",
......
......@@ -19,14 +19,16 @@ description:
## Endpoint
```
GET /_signals/watch/{watch_id}
GET /_signals/watch/{tenant_id}/{watch_id}
```
Retrieves the configuration of a watch identified by the `{watch_id}` path parameter.
Retrieves the configuration of the specified watch.
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
**{watch_id}** The id of the watch to be retrieved. Required.
## Responses
......@@ -45,12 +47,6 @@ The user does not have the required to access the endpoint for the selected tena
A watch with the given id does not exist for the selected tenant.
The status 404 is also returned if the tenant specified by the `sg_tenant` request header does not exist.
## Multi Tenancy
The watch REST API is tenant-aware. Each Signals tenant has its own separate set of watches. The HTTP request header `sg_tenant` can be used to specify the tenant to be used. If the header is absent, the default tenant is used.
## Permissions
To access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/get` for the currently selected tenant.
......@@ -64,7 +60,7 @@ This permission is included in the following [built-in action groups](security_p
## Examples
```
GET /_signals/watch/bad_weather
GET /_signals/watch/_main/bad_weather
```
**Response**
......
......@@ -20,15 +20,17 @@ description:
## Endpoint
```
PUT /_signals/watch/{watch_id}
PUT /_signals/watch/{tenant_id}/{watch_id}
```
Stores or updates a watch identified by the `{watch_id}` path parameter. By default, the watch will be active and scheduled for execution.
Stores or updates a watch identified by the `{watch_id}` path parameter into the tenant specified by the `{tenant_id}` parameter. By default, the watch will be active and scheduled for execution.
**Important** When a watch is created or updated, a snapshot of the privileges of the user performing the operation will be stored with the watch. When the stored watch is executed, it will have exactly these privileges. If a user modifies a watch created by another user, the user must ensure that they still have enough privileges to allow successful execution of the watch. See also the chapter on the [security execution context](security_execution_context.md).
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
**{watch_id}** The id of the watch to be created or updated. Required.
## Request Body
......@@ -51,10 +53,6 @@ The request was malformed.
If the watch specified in the request body was malformed, a JSON document containing detailed validation errors will be returned in the response body. See TODO for details.
### 404 Not found
The tenant specified by the `sg_tenant` request header does not exist.
### 403 Forbidden
The user does not have the permission to create watches for the currently selected tenant.
......@@ -65,10 +63,6 @@ The user does not have the permission to create watches for the currently select
The watch was not encoded as JSON document. Watches need to be sent using the media type application/json.
## Multi Tenancy
The watch REST API is tenant-aware. Each Signals tenant has its own separate set of watches. The HTTP request header `sg_tenant` can be used to specify the tenant to be used. If the header is absent, the default tenant is used.
## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/put` for the currently selected tenant.
......@@ -83,7 +77,7 @@ This permission is included in the following [built-in action groups](security_p
### Basic
```
PUT /_signals/watch/bad_weather
PUT /_signals/watch/_main/bad_weather
```
```json
{
......@@ -163,7 +157,7 @@ PUT /_signals/watch/bad_weather
### Invalid Watch
```
PUT /_signals/watch/really_bad_weather
PUT /_signals/watch/_main/really_bad_weather
```
```json
{
......
......@@ -20,17 +20,21 @@ description:
## Endpoint
```
GET /_signals/watch/_search
GET /_signals/watch/{tenant_id}/_search
```
```
POST /_signals/watch/_search
POST /_signals/watch/{tenant_id}/_search
```
Searches for watches. Search criteria and options can be specified in a manner similar to the Elasticsearch document search REST API.
Searches for watches stored for the specified tenant. Search criteria and options can be specified in a manner similar to the Elasticsearch document search REST API.
Both the GET and the POST HTTP method can be used with the same effect.
## Path Parameters
**{tenant_id}** The Signals tenant to be used. Specify `_main` to select the default tenant. If multi tenancy is disabled, `_main` is the only possible value.
## Query Parameters
**from:** Specifies an offset into the result list. Starting from this offset, the results will be returned. Optional.
......@@ -64,10 +68,6 @@ The search was successfully executed.
The user does not have the required to access the endpoint for the selected tenant.
## Multi Tenancy
The watch REST API is tenant-aware. Each Signals tenant has its own separate set of watches. The HTTP request header `sg_tenant` can be used to specify the tenant to be used. If the header is absent, the default tenant is used.
## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/search` for the currently selected tenant.
......@@ -83,7 +83,7 @@ This permission is included in the following [built-in action groups](security_p
### List all watches
```
GET /_signals/watch/_search?size=1000
GET /_signals/watch/_main/_search?size=1000
```
**Response**
......@@ -110,9 +110,9 @@ GET /_signals/watch/_search?size=1000
"max_score": 0.13353139,
"hits": [
{
"_index": ".signals_main_watches",
"_index": ".signals_watches",
"_type": "_doc",
"_id": "bad_weather",
"_id": "_main/bad_weather",
"_score": 0.13353139,
"_source": {
"checks": [
......@@ -189,7 +189,7 @@ GET /_signals/watch/_search?size=1000
### Search for all watches using an email action
```
POST /_signals/watch/_search?size=1000
POST /_signals/watch/_main/_search?size=1000
```
```
......@@ -226,9 +226,9 @@ POST /_signals/watch/_search?size=1000
"max_score": 0.13353139,
"hits": [
{
"_index": ".signals_main_watches",
"_index": ".signals_watches",
"_type": "_doc",
"_id": "bad_weather",
"_id": "_main/bad_weather",
"_score": 0.13353139,
"_source": {
"checks": [
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment