Skip to content

Commit 425acb6

Browse files
rrelledgerrelledge
committed
DOC-5354 Added missing CRDB requests and fields to RS REST API reference
1 parent 381ac87 commit 425acb6

File tree

6 files changed

+120
-5
lines changed

6 files changed

+120
-5
lines changed

‎content/operate/rs/references/rest-api/objects/crdb/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,5 +25,11 @@ An object that represents an Active-Active database.
2525
"bdb_uid": string,
2626
"id": integer
2727
}, ...] {{</code>}} | Mapping of instance IDs for local databases to local BDB IDs |
28+
| managed_by | string | The component that manages the Active-Active database |
29+
| modules | {{<code>}}[{
30+
"featureset_version": integer,
31+
"module_name": string
32+
}, ...] {{</code>}} | Modules used by the Active-Active database |
2833
| name | string | Name of Active-Active database |
2934
| protocol_version | integer | Active-Active database active protocol version |
35+
| volatile_config_fields | array of strings | A list of database configuration fields that will be set even if unchanged |

‎content/operate/rs/references/rest-api/objects/crdb_task.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,24 @@ An object that represents an Active-Active (CRDB) task.
1414

1515
| Name | Type/Value | Description |
1616
|------|------------|-------------|
17-
| id | string | CRDB task ID (read only) |
17+
| id | string | CRDB task ID (read-only) |
1818
| crdb_guid | string | Globally unique Active-Active database ID (GUID) (read-only) |
19+
| ended | string | Timestamp when the task ended (read-only) |
1920
| errors | {{<code>}}
2021
[{
2122
"cluster_name": string,
2223
"description": string,
2324
"error_code": string
2425
}, ...] {{</code>}} | Details for errors that occurred on a cluster |
25-
| status | 'queued' <br />'started' <br />'finished' <br />'failed' | CRDB task status (read only) |
26+
| operation | string | The operation that is running (read-only) |
27+
| progress | {{<code>}}
28+
{
29+
"clusters": [{
30+
"name": string,
31+
"progress": string
32+
}, ...],
33+
"worker": string
34+
} {{</code>}} | • `name`: The instance cluster name<br />• `progress`: The step the instance coordinator is running<br />• `worker`: The step the worker is running |
35+
| started | string | Timestamp when the task started (read-only) |
36+
| status | 'queued' <br />'started' <br />'finished' <br />'failed' | CRDB task status (read-only) |
37+
| worker_name | string | The worker that runs the task (read-only) |

‎content/operate/rs/references/rest-api/requests/crdb_tasks/_index.md‎

Lines changed: 82 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,36 @@ weight: $weight
1414

1515
| Method | Path | Description |
1616
|--------|------|-------------|
17+
| [GET](#get-all-crdb_tasks) | `/v1/crdb_tasks` | Get all running tasks |
1718
| [GET](#get-crdb_task) | `/v1/crdb_tasks/{task_id}` | Get the status of an executed task |
19+
| [POST](#post-crdb_task-cancel) | `/v1/crdb_tasks/{task_id}/actions/cancel` | Cancel a running or queued task |
20+
21+
## Get all running tasks {#get-all-crdb_tasks}
22+
23+
```sh
24+
GET /v1/crdb_tasks
25+
```
26+
27+
Get all running tasks.
28+
29+
### Request {#get-all-request}
30+
31+
#### Example HTTP request
32+
33+
```sh
34+
GET /v1/crdb_tasks
35+
```
36+
37+
### Response {#get-all-response}
38+
39+
Returns a JSON array of [CRDB task objects]({{< relref "/operate/rs/references/rest-api/objects/crdb_task" >}}).
40+
41+
#### Status codes {#get-all-status-codes}
42+
43+
| Code | Description |
44+
|------|-------------|
45+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | A list of running tasks. |
46+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. |
1847

1948
## Get task status {#get-crdb_task}
2049

@@ -42,6 +71,12 @@ The status of a completed task is kept for 500 seconds by default.
4271
|-------|------|-------------|
4372
| task_id | string | Task ID |
4473

74+
#### Query parameters
75+
76+
| Field | Type | Description |
77+
|-------|------|-------------|
78+
| verbose | boolean | Return detailed task information (optional) |
79+
4580
### Response {#get-response}
4681

4782
Returns a [CRDB task object]({{< relref "/operate/rs/references/rest-api/objects/crdb_task" >}}).
@@ -50,6 +85,50 @@ Returns a [CRDB task object]({{< relref "/operate/rs/references/rest-api/objects
5085

5186
| Code | Description |
5287
|------|-------------|
53-
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Task status. |
54-
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | Unauthorized request. Invalid credentials |
55-
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Task not found. |
88+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Task status. |
89+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials |
90+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. |
91+
92+
## Cancel task {#post-crdb_task-cancel}
93+
94+
```sh
95+
POST /v1/crdb_tasks/{task_id}/actions/cancel
96+
```
97+
98+
Gracefully cancels a running or queued task.
99+
100+
A task that already reached the commit phase cannot be canceled.
101+
102+
### Request {#post-cancel-request}
103+
104+
#### Example HTTP request
105+
106+
```sh
107+
POST /v1/crdb_tasks/1/actions/cancel
108+
```
109+
110+
#### URL parameters
111+
112+
| Field | Type | Description |
113+
|-------|------|-------------|
114+
| task_id | string | Task ID |
115+
116+
#### Query parameters
117+
118+
| Field | Type | Description |
119+
|-------|------|-------------|
120+
| force | boolean | Cancel even if the task is in the commit phase. **WARNING**: This can break the CRDB in the cluster configuration store (CCS), so use with caution. (optional) |
121+
122+
### Response {#post-cancel-response}
123+
124+
Returns a status code.
125+
126+
#### Status codes {#post-cancel-status-codes}
127+
128+
| Code | Description |
129+
|------|-------------|
130+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request has been accepted. |
131+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. |
132+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. |
133+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Task cannot be canceled. |
134+
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Failed to cancel task. |

‎content/operate/rs/references/rest-api/requests/crdbs/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,12 @@ Create a new Active-Active database.
173173
| X-Task-ID | string | Specified task ID |
174174
| X-Result-TTL | integer | Time (in seconds) to keep task result |
175175

176+
#### Query parameters
177+
178+
| Field | Type | Description |
179+
|-------|------|-------------|
180+
| dry_run | boolean | Validate the request without creating the database (optional) |
181+
176182
#### Request body
177183

178184
Include a [CRDB object]({{< relref "/operate/rs/references/rest-api/objects/crdb" >}}), which defines the Active-Active database, in the request body.

‎content/operate/rs/references/rest-api/requests/crdbs/flush.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,12 @@ PUT /v1/crdbs/552bbccb-99f3-4142-bd17-93d245f0bc79/flush
4444
|-------|------|-------------|
4545
| crdb_guid | string | Globally unique Active-Active database ID (GUID) |
4646

47+
#### Query parameters
48+
49+
| Field | Type | Description |
50+
|-------|------|-------------|
51+
| async_flush | boolean | Perform asynchronous flush operation (optional) |
52+
4753
### Response {#put-response}
4854

4955
Returns a [CRDB task object]({{< relref "/operate/rs/references/rest-api/objects/crdb_task" >}}).

‎content/operate/rs/references/rest-api/requests/crdbs/updates.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,12 @@ When you update db_config, it changes the configuration of the database that you
5050
|-------|------|-------------|
5151
| crdb_guid | string | Globally unique Active-Active database ID (GUID) |
5252

53+
#### Query parameters
54+
55+
| Field | Type | Description |
56+
|-------|------|-------------|
57+
| dry_run | boolean | Validate the request without applying changes (optional) |
58+
5359
#### Request body
5460

5561
Include a [CRDB modify_request object]({{< relref "/operate/rs/references/rest-api/objects/crdb/modify_request" >}}) with updated fields in the request body.

0 commit comments

Comments
 (0)