Skip to content

Commit a49b0fd

Browse files
rrelledgerrelledge
committed
DOC-4812 RS: Added /v2/actions REST API reference
1 parent d8f50b7 commit a49b0fd

File tree

1 file changed

+166
-4
lines changed
  • content/operate/rs/references/rest-api/requests/actions

1 file changed

+166
-4
lines changed

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

+166-4
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,9 @@ weight: $weight
1515
| Method | Path | Description |
1616
|--------|------|-------------|
1717
| [GET](#get-all-actions) | `/v1/actions` | Get all actions |
18+
| [GET](#get-all-actions-v2) | `/v2/actions` | Get all actions |
1819
| [GET](#get-action) | `/v1/actions/{uid}` | Get a single action |
20+
| [GET](#get-action-v2) | `/v2/actions/{uid}` | Get a single action |
1921

2022
## Get all actions {#get-all-actions}
2123

@@ -25,6 +27,8 @@ GET /v1/actions
2527

2628
Get the status of all running, pending, or completed actions on all clusters, nodes, and databases. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`.
2729

30+
This API does not return any information about other actions, such as import, export, and backup. To get info about these actions, use [`GET /v2/actions`](#get-all-actions-v2).
31+
2832
#### Required permissions
2933

3034
| Permission name |
@@ -95,8 +99,84 @@ Regardless of an action’s source, each action in the response contains the fol
9599

96100
| Code | Description |
97101
|------|-------------|
98-
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about an ongoing action |
99-
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run).|
102+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |
103+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (i.e. not currently running and no available status of last run).|
104+
105+
## Get all actions {#get-all-actions-v2}
106+
107+
```
108+
GET /v2/actions
109+
```
110+
111+
Get the status of all currently running, pending, or completed actions from tasks, state-machines, and other actions, including import, export, and backup. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`.
112+
113+
#### Required permissions
114+
115+
| Permission name |
116+
|-----------------|
117+
| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) |
118+
119+
### Request {#get-all-request-v2}
120+
121+
#### Example HTTP request
122+
123+
```
124+
GET /v2/actions
125+
```
126+
127+
### Response {#get-all-response-v2}
128+
129+
Returns a JSON array of v2 [action objects]({{< relref "/operate/rs/references/rest-api/objects/action" >}}).
130+
131+
The v2 action object includes the following fields:
132+
133+
| Field | Type/Value | Description |
134+
|-------|------------|-------------|
135+
| action_uid | string | The action's globally unique identifier |
136+
| action_type | "task"<br />"state-machine"<br />"other" | The action's type |
137+
| creation_time | integer | The action's creation time. Unix timestamp in seconds. |
138+
| name | string | Name of the running or failed state machine |
139+
| progress | float (range: 0-100) | Percent of completed steps for the action |
140+
| status | "pending"<br />"active"<br />"completed"<br />"failed" | The action's status |
141+
| additional_info | JSON object | A dictionary that can include additional information about the action |
142+
143+
The `additional_info` object can contain any of the following fields:
144+
145+
| Field | Type/Value | Description |
146+
|-------|------------|-------------|
147+
| description | string | Short description of the action |
148+
| error | string | A message that describes what error occurred if the action failed |
149+
| object_type | string | The type of object that was processed in the action, such as BDB or node |
150+
| object_uid | string | The unique ID of the object processed in the action |
151+
| pending_ops | JSON object | List of operations that are waiting to run (optional)<br />{{<code>}}"pending_ops": {<br /> "3": {<br /> "heartbeat": integer,<br /> "snapshot": { ... },<br /> "last_sample_time": integer,<br /> "op_name": string,<br /> "status_code": string,<br /> "status_description": string,<br /> "progress": float<br /> }<br />}{{</code>}}<br />`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:<br />**heartbeat**: The last time in seconds since the epoch when a snapshot of the operation was saved.<br />**snapshot**: A map of properties stored by the operation that are needed to run.<br />**last_sample_time**: The last time in seconds since the epoch when a snapshot of the operation was saved.<br />**op_name**: The name of the operation from the state machine that is running.<br />**status_code**: The code for the operation's current status.<br />**status_description**: The operation's current status.<br />**progress**: The operation's progress in percentage (1 to 100). |
152+
153+
Regardless of an action’s source, each action in the response contains the following attributes: `name`, `action_uid`, `status`, and `progress`.
154+
155+
#### Example JSON body
156+
157+
```json
158+
[
159+
{
160+
"action_type": "task",
161+
"action_uid": "6155403f-c26f-40ab-8afc-23ed663973f6",
162+
"additional_info": {
163+
"object_type": "node",
164+
"object_uid": "1"
165+
},
166+
"creation_time": 1742595918,
167+
"name": "retry_bdb",
168+
"progress": 100.0,
169+
"status": "completed"
170+
},
171+
// Additional task objects
172+
]
173+
```
174+
175+
### Status codes {#get-all-status-codes-v2}
176+
177+
| Code | Description |
178+
|------|-------------|
179+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |
100180

101181
## Get a specific action {#get-action}
102182

@@ -106,6 +186,8 @@ GET /v1/actions/{uid}
106186

107187
Get the status of a specific action.
108188

189+
This API does not return any information about other actions, such as import, export, and backup. To get info about these actions, use [`GET /v2/actions/<uid>`](#get-action-v2).
190+
109191
#### Required permissions
110192

111193
| Permission name |
@@ -160,5 +242,85 @@ Regardless of an action’s source, each action contains the following attribute
160242

161243
| Code | Description |
162244
|------|-------------|
163-
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about an ongoing action |
164-
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run) |
245+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |
246+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (i.e. not currently running and no available status of last run) |
247+
248+
## Get a specific action {#get-action-v2}
249+
250+
```
251+
GET /v2/actions/{uid}
252+
```
253+
254+
Get the status of a specific action. This API can also return information about actions like import, export, and backup.
255+
256+
#### Required permissions
257+
258+
| Permission name |
259+
|-----------------|
260+
| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) |
261+
262+
### Request {#get-request-v2}
263+
264+
#### Example HTTP request
265+
266+
```
267+
GET /v2/actions/{uid}
268+
```
269+
270+
#### URL parameters
271+
272+
| Field | Type | Description |
273+
|-------|------|-------------|
274+
| uid | string | The action_uid to check |
275+
276+
### Response {#get-response-v2}
277+
278+
Returns a v2 [action object]({{<relref "/operate/rs/references/rest-api/objects/action">}}).
279+
280+
The v2 action object includes the following fields:
281+
282+
| Field | Type/Value | Description |
283+
|-------|------------|-------------|
284+
| action_uid | string | The action's globally unique identifier |
285+
| action_type | "task"<br />"state-machine"<br />"other" | The action's type |
286+
| creation_time | integer | The action's creation time. Unix timestamp in seconds. |
287+
| name | string | Name of the running or failed state machine |
288+
| progress | float (range: 0-100) | Percent of completed steps for the action |
289+
| status | "pending"<br />"active"<br />"completed"<br />"failed" | The action's status |
290+
| additional_info | JSON object | A dictionary that can include additional information about the action |
291+
292+
The `additional_info` object can contain any of the following fields:
293+
294+
| Field | Type/Value | Description |
295+
|-------|------------|-------------|
296+
| description | string | Short description of the action |
297+
| error | string | A message that describes what error occurred if the action failed |
298+
| object_type | string | The type of object that was processed in the action, such as BDB or node |
299+
| object_uid | string | The unique ID of the object processed in the action |
300+
| pending_ops | JSON object | List of operations that are waiting to run (optional)<br />{{<code>}}"pending_ops": {<br /> "3": {<br /> "heartbeat": integer,<br /> "snapshot": { ... },<br /> "last_sample_time": integer,<br /> "op_name": string,<br /> "status_code": string,<br /> "status_description": string,<br /> "progress": float<br /> }<br />}{{</code>}}<br />`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:<br />**heartbeat**: The last time in seconds since the epoch when a snapshot of the operation was saved.<br />**snapshot**: A map of properties stored by the operation that are needed to run.<br />**last_sample_time**: The last time in seconds since the epoch when a snapshot of the operation was saved.<br />**op_name**: The name of the operation from the state machine that is running.<br />**status_code**: The code for the operation's current status.<br />**status_description**: The operation's current status.<br />**progress**: The operation's progress in percentage (1 to 100). |
301+
302+
Regardless of an action’s source, each action contains the following attributes: `name`, `action_uid`, `status`, and `progress`.
303+
304+
#### Example JSON body
305+
306+
```json
307+
{
308+
"action_type": "task",
309+
"action_uid": "6155403f-c26f-40ab-8afc-23ed663973f6",
310+
"additional_info": {
311+
"object_type": "node",
312+
"object_uid": "1"
313+
},
314+
"creation_time": 1742595918,
315+
"name": "retry_bdb",
316+
"progress": 100.0,
317+
"status": "completed"
318+
}
319+
```
320+
321+
### Status codes {#get-status-codes-v2}
322+
323+
| Code | Description |
324+
|------|-------------|
325+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |
326+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (i.e. not currently running and no available status of last run) |

0 commit comments

Comments
 (0)