Skip to content

Commit d1dcaa3

Browse files
rrelledgerrelledge
committed
DOC-5680 Added user-defined modules REST API requests reference
1 parent cc5069d commit d1dcaa3

File tree

1 file changed

+303
-0
lines changed

1 file changed

+303
-0
lines changed

‎content/operate/rs/references/rest-api/requests/modules/user-defined.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
---
2+
Title: User-defined module requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: Custom, user-defined Redis module requests
9+
headerRange: '[1-2]'
10+
linkTitle: user-defined
11+
weight: $weight
12+
---
13+
14+
| Method | Path | Description |
15+
|--------|------|-------------|
16+
| [GET](#get-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts | List custom module artifacts on a node |
17+
| [POST](#post-user-defined-module) | /v2/modules/user-defined | Create a custom module object in the CCS |
18+
| [POST](#post-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts | Upload a custom module artifact to a node |
19+
| [DELETE](#delete-user-defined-module) | /v2/modules/user-defined/<uid> | Delete a custom module object from the CCS |
20+
| [DELETE](#delete-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts/<module_name>/<version> | Delete a custom module artifact from a node |
21+
22+
## List custom module artifacts {#get-local-user-defined-artifacts}
23+
24+
```sh
25+
GET /v2/local/modules/user-defined/artifacts
26+
```
27+
28+
Returns a list of all custom module artifacts on the local node.
29+
30+
#### Permissions
31+
32+
| Permission name | Roles |
33+
|-----------------|-------|
34+
| [view_cluster_modules]({{< relref "/operate/rs/references/rest-api/permissions#view_cluster_modules" >}}) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |
35+
36+
### Request {#get-local-artifacts-request}
37+
38+
#### Example HTTP request
39+
40+
```sh
41+
GET /v2/local/modules/user-defined/artifacts
42+
```
43+
44+
#### Headers
45+
46+
| Key | Value | Description |
47+
|-----|-------|-------------|
48+
| Host | cnm.cluster.fqdn | Domain name |
49+
| Accept | \*/\* | Accepted media type |
50+
51+
### Response {#get-local-artifacts-response}
52+
53+
Returns a JSON array of custom module artifacts.
54+
55+
#### Example JSON body
56+
57+
```json
58+
[
59+
{
60+
"module_name": "TestModule",
61+
"version": 123,
62+
"dependencies": [
63+
"dep_1",
64+
"dep_2"
65+
]
66+
}
67+
]
68+
```
69+
70+
### Status codes {#get-local-artifacts-status-codes}
71+
72+
| Code | Description |
73+
|------|-------------|
74+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, returns list of artifacts |
75+
76+
## Create custom module {#post-user-defined-module}
77+
78+
```sh
79+
POST /v2/modules/user-defined
80+
```
81+
82+
Creates a module object in the CCS. After calling this endpoint, you still need to upload the module's `.so` file to each node by calling [`POST /v2/local/modules/user-defined/artifacts`](#post-local-user-defined-artifacts) on each node.
83+
84+
#### Permissions
85+
86+
| Permission name | Roles |
87+
|-----------------|-------|
88+
| [manage_cluster_modules]({{< relref "/operate/rs/references/rest-api/permissions#manage_cluster_modules" >}}) | admin |
89+
90+
### Request {#post-user-defined-request}
91+
92+
#### Example HTTP request
93+
94+
```sh
95+
POST /v2/modules/user-defined
96+
```
97+
98+
#### Example JSON body
99+
100+
```json
101+
{
102+
"module_name": "TestModule",
103+
"version": 1,
104+
"semantic_version": "0.0.1",
105+
"display_name": "test module",
106+
"commands": [
107+
{
108+
"command_arity": -1,
109+
"command_name": "json.arrtrim",
110+
"first_key": 1,
111+
"flags": ["write"],
112+
"last_key": 1,
113+
"step": 1
114+
}
115+
],
116+
"command_line_args": "",
117+
"capabilities": ["list", "of", "capabilities"],
118+
"min_redis_version": "2.1"
119+
}
120+
```
121+
122+
#### Headers
123+
124+
| Key | Value | Description |
125+
|-----|-------|-------------|
126+
| Host | cnm.cluster.fqdn | Domain name |
127+
| Accept | application/json | Accepted media type |
128+
129+
#### Request body
130+
131+
The request body is a JSON object that must contain the following fields:
132+
133+
| Field | Type | Description |
134+
|-------|------|-------------|
135+
| module_name | string | Name of the module |
136+
| version | integer | Module version number |
137+
| semantic_version | string | Module's semantic version |
138+
| display_name | string | Display name for the module |
139+
| commands | array of objects | List of commands provided by the module |
140+
| command_line_args | string | Command line arguments for the module |
141+
| capabilities | array of strings | List of capabilities supported by the module |
142+
| min_redis_version | string | Minimum Redis version required |
143+
144+
### Response {#post-user-defined-response}
145+
146+
Returns a module metadata object.
147+
148+
#### Example JSON body
149+
150+
```json
151+
{
152+
"author": "author name",
153+
"uid": "1952fcf9a5109fb59e61b1ad4d7e2d88"
154+
// additional fields...
155+
}
156+
```
157+
158+
### Status codes {#post-user-defined-status-codes}
159+
160+
| Code | Description |
161+
|------|-------------|
162+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module was created in the CCS. |
163+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | There was an issue with the module object, such as missing required fields or invalid values. |
164+
165+
## Upload custom module artifact to a node {#post-local-user-defined-artifacts}
166+
167+
```sh
168+
POST /v2/local/modules/user-defined/artifacts
169+
```
170+
171+
A local API to upload a custom module's artifact to the current node. You must call this API on each cluster node.
172+
173+
#### Permissions
174+
175+
| Permission name | Roles |
176+
|-----------------|-------|
177+
| [manage_cluster_modules]({{< relref "/operate/rs/references/rest-api/permissions#manage_cluster_modules" >}}) | admin |
178+
179+
### Request {#post-local-artifacts-request}
180+
181+
#### Example HTTP request
182+
183+
```sh
184+
POST /v2/local/modules/user-defined/artifacts
185+
```
186+
187+
#### Headers
188+
189+
| Key | Value | Description |
190+
|-----|-------|-------------|
191+
| Host | 127.0.0.1:9443 | Domain name |
192+
| Accept | \*/\* | Accepted media type |
193+
| Content-Length | 865 | Length of the request body in octets |
194+
| Expect | 100-continue | Requires particular server behaviors |
195+
| Content-Type | multipart/form-data; boundary=------------------------4751ac3b332ace13 | Media type of request/response body |
196+
197+
### Response {#post-local-artifacts-response}
198+
199+
Returns a status code to indicate upload success or failure.
200+
201+
### Status codes {#post-local-artifacts-status-codes}
202+
203+
| Code | Description |
204+
|------|-------------|
205+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, module artifact uploaded to local node |
206+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Missing or bad artifact |
207+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | There was an issue with the module object artifact, such as bad metadata |
208+
209+
## Delete custom module {#delete-user-defined-module}
210+
211+
```sh
212+
DELETE /v2/modules/user-defined/{string: uid}
213+
```
214+
215+
Delete a module object from the CCS. This REST API request does not delete the module artifact from the nodes, so you also need to call [`DELETE /v2/local/modules/user-defined/artifacts/<module_name>/<version>`](#delete-local-user-defined-artifacts) on each node.
216+
217+
#### Permissions
218+
219+
| Permission name | Roles |
220+
|-----------------|-------|
221+
| [manage_cluster_modules]({{< relref "/operate/rs/references/rest-api/permissions#manage_cluster_modules" >}}) | admin |
222+
223+
### Request {#delete-user-defined-request}
224+
225+
#### Example HTTP request
226+
227+
```sh
228+
DELETE /v2/modules/user-defined/1
229+
```
230+
231+
#### Headers
232+
233+
| Key | Value | Description |
234+
|-----|-------|-------------|
235+
| Host | cnm.cluster.fqdn | Domain name |
236+
| Accept | application/json | Accepted media type |
237+
238+
#### URL parameters
239+
240+
| Field | Type | Description |
241+
|-------|------|-------------|
242+
| uid | string | The module's unique ID |
243+
244+
### Response {#delete-user-defined-response}
245+
246+
Returns a status code to indicate module deletion success or failure.
247+
248+
### Status codes {#delete-user-defined-status-codes}
249+
250+
| Code | Description |
251+
|------|-------------|
252+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module is deleted. |
253+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to delete a non-existing module. |
254+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The request is not acceptable. |
255+
256+
257+
## Delete custom module artifact from a node{#delete-local-user-defined-artifacts}
258+
259+
```sh
260+
DELETE /v2/local/modules/user-defined/artifacts/{string: module_name}/{int: version}
261+
```
262+
263+
A local API to delete a custom module's artifact from the current node. You must call this API on each cluster node.
264+
265+
#### Permissions
266+
267+
| Permission name | Roles |
268+
|-----------------|-------|
269+
| [manage_cluster_modules]({{< relref "/operate/rs/references/rest-api/permissions#manage_cluster_modules" >}}) | admin |
270+
271+
### Request {#delete-local-artifacts-request}
272+
273+
#### Example HTTP request
274+
275+
```sh
276+
DELETE /v2/local/modules/user-defined/artifacts/some-custom-module/123
277+
```
278+
279+
#### Headers
280+
281+
| Key | Value | Description |
282+
|-----|-------|-------------|
283+
| Host | cnm.cluster.fqdn | Domain name |
284+
| Accept | application/json | Accepted media type |
285+
286+
#### URL parameters
287+
288+
| Field | Type | Description |
289+
|-------|------|-------------|
290+
| module_name | string | The name of the module artifact to delete |
291+
| version | integer | The version of the module artifact to delete |
292+
293+
### Response {#delete-local-artifacts-response}
294+
295+
Returns a status code to indicate deletion success or failure.
296+
297+
### Status codes {#delete-local-artifacts-status-codes}
298+
299+
| Code | Description |
300+
|------|-------------|
301+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module artifact is deleted from the local node. |
302+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to delete a non-existing module. |
303+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The request is not acceptable. |

0 commit comments

Comments
 (0)