Skip to content

Commit f60a051

Browse files
rrelledgerrelledge
authored
RS: Add services REST API reference (#1164)
* DOC-3669 RS: Add REST API reference for /services * DOC-3669 Feedback update - only list start, stop, restart operations for services API * DOC-3669 Feedback update to note the POST services request should be used for optional services only * Fix 200 OK links * DOC-3669 Feedback update to emphasize the warning that this API is dangerous
1 parent c0f94b8 commit f60a051

File tree

1 file changed

+224
-0
lines changed
  • content/operate/rs/references/rest-api/requests/services

1 file changed

+224
-0
lines changed

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

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
Title: Services requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: REST API requests to list or modify Redis Enterprise services.
9+
headerRange: '[1-2]'
10+
hideListLinks: true
11+
linkTitle: services
12+
weight: $weight
13+
---
14+
15+
| Method | Path | Description |
16+
|--------|------|-------------|
17+
| [GET](#get-local-services) | `/v1/local/services` | List Redis Enterprise services on the local node |
18+
| [POST](#post-local-services) | `/v1/local/services` | Modify or perform operations on local processes |
19+
| [POST](#post-services) | `/v1/services` | Apply cluster-wide changes to services |
20+
21+
{{<warning>}}
22+
This API is dangerous and should only be run with guidance from [Redis support](https://redis.io/support/).
23+
24+
Stop, start, or restart optional services only. Changing the status of required services can negatively affect cluster behavior and cause a complete loss of the cluster and its data.
25+
26+
For a list of optional services, see the [services configuration object reference]({{<relref "/operate/rs/references/rest-api/objects/services_configuration">}}) or use a [`GET /v1/cluster/services_configuration`]({{<relref "/operate/rs/references/rest-api/requests/cluster/services_configuration#get-cluster-services_config">}}) request.
27+
{{</warning>}}
28+
29+
## Get local services {#get-local-services}
30+
31+
```sh
32+
GET /v1/local/services
33+
```
34+
35+
Lists all Redis Enterprise services currently running on the local node and relevant metadata.
36+
37+
### Request {#get-request}
38+
39+
#### Example HTTP request
40+
41+
```sh
42+
GET /local/services
43+
```
44+
45+
46+
#### Headers
47+
48+
| Key | Value | Description |
49+
|-----|-------|-------------|
50+
| Host | cnm.cluster.fqdn | Domain name |
51+
| Accept | application/json | Accepted media type |
52+
53+
54+
### Response {#get-response}
55+
56+
Returns a JSON object that describes all Redis Enterprise services currently running on the local node and relevant metadata.
57+
58+
Possible `status` values:
59+
- RESTARTING
60+
- RUNNING
61+
- STARTING
62+
- STOPPED
63+
64+
#### Example JSON response body
65+
66+
```json
67+
{
68+
"alert_mgr": {
69+
"start_time": "2024-05-13T18:38:00Z",
70+
"status": "RUNNING",
71+
"uptime": "3 days, 0:58:59"
72+
},
73+
"ccs": {
74+
"start_time": "2024-05-13T18:38:59Z",
75+
"status": "RUNNING",
76+
"uptime": "3 days, 0:58:00"
77+
},
78+
...
79+
}
80+
```
81+
82+
#### Status codes {#get-status-codes}
83+
84+
| Code | Description |
85+
|------|-------------|
86+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error |
87+
88+
## Modify local services {#post-local-services}
89+
90+
```sh
91+
POST /v1/local/services
92+
```
93+
94+
Modify Redis Enterprise services or perform operations that directly interact with processes. For cluster-wide changes that are not node-specific, use [`POST /v1/services`](#post-services) instead.
95+
96+
Supported `operation_type` values:
97+
98+
- stop
99+
- start
100+
- restart
101+
102+
{{<warning>}}
103+
This API is dangerous and should only be run with guidance from [Redis support](https://redis.io/support/).
104+
105+
Stop, start, or restart optional services only. Changing the status of required services can negatively affect cluster behavior and cause a complete loss of the cluster and its data.
106+
107+
For a list of optional services, see the [services configuration object reference]({{<relref "/operate/rs/references/rest-api/objects/services_configuration">}}) or use a [`GET /v1/cluster/services_configuration`]({{<relref "/operate/rs/references/rest-api/requests/cluster/services_configuration#get-cluster-services_config">}}) request.
108+
{{</warning>}}
109+
110+
### Request {#post-local-request}
111+
112+
#### Example HTTP request
113+
114+
```sh
115+
POST /local/services
116+
```
117+
118+
#### Headers
119+
120+
| Key | Value | Description |
121+
|-----|-------|-------------|
122+
| Host | cnm.cluster.fqdn | Domain name |
123+
| Accept | application/json | Accepted media type |
124+
125+
126+
#### Example JSON request body
127+
128+
```json
129+
{
130+
"operation_type": "restart",
131+
"services": [
132+
"alert_mgr"
133+
]
134+
}
135+
```
136+
137+
### Response {#post-local-response}
138+
139+
Returns a JSON object that shows whether the operation ran successfully or failed for each requested service.
140+
141+
#### Example JSON response body
142+
143+
```json
144+
{
145+
"alert_mgr": true,
146+
"metrics_exporter": true
147+
}
148+
```
149+
150+
151+
#### Status codes {#post-local-status-codes}
152+
153+
| Code | Description |
154+
|------|-------------|
155+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |
156+
157+
## Apply cluster-wide service changes {#post-services}
158+
159+
```sh
160+
POST /v1/services
161+
```
162+
163+
Makes cluster-wide changes that are not node-specific on Redis Enterprise services. The master node handles these changes. For operations that directly interact with processes, use [`POST /v1/local/services`](#post-local-services) instead.
164+
165+
Supported `operation_type` values:
166+
167+
- stop
168+
- start
169+
- restart
170+
171+
{{<warning>}}
172+
This API is dangerous and should only be run with guidance from [Redis support](https://redis.io/support/).
173+
174+
Stop, start, or restart optional services only. Changing the status of required services can negatively affect cluster behavior and cause a complete loss of the cluster and its data.
175+
176+
For a list of optional services, see the [services configuration object reference]({{<relref "/operate/rs/references/rest-api/objects/services_configuration">}}) or use a [`GET /v1/cluster/services_configuration`]({{<relref "/operate/rs/references/rest-api/requests/cluster/services_configuration#get-cluster-services_config">}}) request.
177+
{{</warning>}}
178+
179+
### Request {#post-request}
180+
181+
#### Example HTTP request
182+
183+
```sh
184+
POST /services
185+
```
186+
187+
#### Headers
188+
189+
| Key | Value | Description |
190+
|-----|-------|-------------|
191+
| Host | cnm.cluster.fqdn | Domain name |
192+
| Accept | application/json | Accepted media type |
193+
194+
195+
#### Example JSON request body
196+
197+
```json
198+
{
199+
"operation_type": "restart",
200+
"services": [
201+
"alert_mgr"
202+
]
203+
}
204+
```
205+
206+
### Response {#post-response}
207+
208+
Returns a JSON object that shows whether the operation ran successfully or failed for each requested service.
209+
210+
#### Example JSON response body
211+
212+
```json
213+
{
214+
"alert_mgr": true,
215+
"metrics_exporter": true
216+
}
217+
```
218+
219+
220+
#### Status codes {#post-status-codes}
221+
222+
| Code | Description |
223+
|------|-------------|
224+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |

0 commit comments

Comments
 (0)