0
# REST API Management
1
2
HTTP REST API endpoints for runtime scheduler and job management. Provides programmatic access to all scheduler operations through HTTP requests with JSON responses. API endpoints are automatically registered when `SCHEDULER_API_ENABLED` is True.
3
4
## Capabilities
5
6
### Scheduler Management API
7
8
HTTP endpoints for controlling scheduler lifecycle and getting status information.
9
10
```python { .api }
11
def get_scheduler_info():
12
"""
13
Gets the scheduler info.
14
15
HTTP: GET /scheduler
16
17
Returns:
18
JSON response with:
19
current_host (str): Current hostname
20
allowed_hosts (list): List of allowed hostnames
21
running (bool): Whether scheduler is running
22
"""
23
24
def pause_scheduler():
25
"""
26
Pauses job processing in the scheduler.
27
28
HTTP: POST /scheduler/pause
29
30
Returns:
31
HTTP 204: Success
32
HTTP 500: Error with {"error_message": str}
33
"""
34
35
def resume_scheduler():
36
"""
37
Resumes job processing in the scheduler.
38
39
HTTP: POST /scheduler/resume
40
41
Returns:
42
HTTP 204: Success
43
HTTP 500: Error with {"error_message": str}
44
"""
45
46
def start_scheduler():
47
"""
48
Starts the scheduler.
49
50
HTTP: POST /scheduler/start
51
52
Returns:
53
HTTP 204: Success
54
HTTP 400: SchedulerAlreadyRunningError
55
HTTP 500: Other errors with {"error_message": str}
56
"""
57
58
def shutdown_scheduler():
59
"""
60
Shuts down the scheduler.
61
62
HTTP: POST /scheduler/shutdown
63
64
Request Body (JSON, optional):
65
wait (bool): Wait for running jobs to finish (default: true)
66
67
Returns:
68
HTTP 204: Success
69
HTTP 400: SchedulerNotRunningError
70
HTTP 500: Other errors with {"error_message": str}
71
"""
72
```
73
74
### Job Management API
75
76
HTTP endpoints for managing individual jobs and job collections.
77
78
```python { .api }
79
def add_job():
80
"""
81
Adds a new job.
82
83
HTTP: POST /scheduler/jobs
84
85
Request Body (JSON):
86
id (str): Job identifier
87
func (str): Function reference (e.g., "module:function")
88
trigger (str): Trigger type ("date", "interval", "cron")
89
[trigger parameters]: Based on trigger type
90
[job options]: name, misfire_grace_time, max_instances, etc.
91
92
Returns:
93
HTTP 200: Job object as JSON
94
HTTP 409: ConflictingIdError if job ID already exists
95
HTTP 500: Other errors with {"error_message": str}
96
"""
97
98
def get_jobs():
99
"""
100
Gets all scheduled jobs.
101
102
HTTP: GET /scheduler/jobs
103
104
Returns:
105
JSON array of job objects with:
106
id, name, func, args, kwargs, trigger info, next_run_time, etc.
107
"""
108
109
def get_job(job_id):
110
"""
111
Gets a specific job.
112
113
HTTP: GET /scheduler/jobs/{job_id}
114
115
Args:
116
job_id (str): Job identifier from URL path
117
118
Returns:
119
HTTP 200: Job object as JSON
120
HTTP 404: Job not found with {"error_message": str}
121
"""
122
123
def delete_job(job_id):
124
"""
125
Deletes a job.
126
127
HTTP: DELETE /scheduler/jobs/{job_id}
128
129
Args:
130
job_id (str): Job identifier from URL path
131
132
Returns:
133
HTTP 204: Success
134
HTTP 404: Job not found with {"error_message": str}
135
HTTP 500: Other errors with {"error_message": str}
136
"""
137
138
def update_job(job_id):
139
"""
140
Updates a job.
141
142
HTTP: PATCH /scheduler/jobs/{job_id}
143
144
Args:
145
job_id (str): Job identifier from URL path
146
147
Request Body (JSON):
148
[job properties]: Any job properties to modify
149
150
Returns:
151
HTTP 200: Updated job object as JSON
152
HTTP 404: Job not found with {"error_message": str}
153
HTTP 500: Other errors with {"error_message": str}
154
"""
155
```
156
157
### Job Control API
158
159
HTTP endpoints for controlling individual job execution.
160
161
```python { .api }
162
def pause_job(job_id):
163
"""
164
Pauses a job.
165
166
HTTP: POST /scheduler/jobs/{job_id}/pause
167
168
Args:
169
job_id (str): Job identifier from URL path
170
171
Returns:
172
HTTP 200: Updated job object as JSON
173
HTTP 404: Job not found with {"error_message": str}
174
HTTP 500: Other errors with {"error_message": str}
175
"""
176
177
def resume_job(job_id):
178
"""
179
Resumes a job.
180
181
HTTP: POST /scheduler/jobs/{job_id}/resume
182
183
Args:
184
job_id (str): Job identifier from URL path
185
186
Returns:
187
HTTP 200: Updated job object as JSON
188
HTTP 404: Job not found with {"error_message": str}
189
HTTP 500: Other errors with {"error_message": str}
190
"""
191
192
def run_job(job_id):
193
"""
194
Executes a job immediately.
195
196
HTTP: POST /scheduler/jobs/{job_id}/run
197
198
Args:
199
job_id (str): Job identifier from URL path
200
201
Returns:
202
HTTP 200: Job object as JSON
203
HTTP 404: Job not found with {"error_message": str}
204
HTTP 500: Other errors with {"error_message": str}
205
"""
206
```
207
208
## API Configuration
209
210
```python { .api }
211
# Flask configuration for API
212
SCHEDULER_API_ENABLED: bool = False # Enable REST API
213
SCHEDULER_API_PREFIX: str = "/scheduler" # API URL prefix
214
SCHEDULER_ENDPOINT_PREFIX: str = "scheduler." # Flask endpoint prefix
215
```
216
217
## Usage Examples
218
219
### Enable REST API
220
221
```python
222
from flask import Flask
223
from flask_apscheduler import APScheduler
224
225
class Config:
226
SCHEDULER_API_ENABLED = True
227
SCHEDULER_API_PREFIX = "/api/scheduler"
228
229
app = Flask(__name__)
230
app.config.from_object(Config())
231
232
scheduler = APScheduler()
233
scheduler.init_app(app)
234
scheduler.start()
235
```
236
237
### Scheduler Management Requests
238
239
```bash
240
# Get scheduler info
241
curl http://localhost:5000/scheduler
242
243
# Start scheduler
244
curl -X POST http://localhost:5000/scheduler/start
245
246
# Pause scheduler
247
curl -X POST http://localhost:5000/scheduler/pause
248
249
# Resume scheduler
250
curl -X POST http://localhost:5000/scheduler/resume
251
252
# Shutdown scheduler (wait for jobs)
253
curl -X POST http://localhost:5000/scheduler/shutdown \
254
-H "Content-Type: application/json" \
255
-d '{"wait": true}'
256
```
257
258
### Job Management Requests
259
260
```bash
261
# Add a new job
262
curl -X POST http://localhost:5000/scheduler/jobs \
263
-H "Content-Type: application/json" \
264
-d '{
265
"id": "test_job",
266
"func": "mymodule:my_function",
267
"trigger": "interval",
268
"seconds": 30,
269
"name": "Test Job"
270
}'
271
272
# Get all jobs
273
curl http://localhost:5000/scheduler/jobs
274
275
# Get specific job
276
curl http://localhost:5000/scheduler/jobs/test_job
277
278
# Update job (change interval)
279
curl -X PATCH http://localhost:5000/scheduler/jobs/test_job \
280
-H "Content-Type: application/json" \
281
-d '{"seconds": 60}'
282
283
# Delete job
284
curl -X DELETE http://localhost:5000/scheduler/jobs/test_job
285
```
286
287
### Job Control Requests
288
289
```bash
290
# Pause job
291
curl -X POST http://localhost:5000/scheduler/jobs/test_job/pause
292
293
# Resume job
294
curl -X POST http://localhost:5000/scheduler/jobs/test_job/resume
295
296
# Run job immediately
297
curl -X POST http://localhost:5000/scheduler/jobs/test_job/run
298
```
299
300
### Advanced Job Creation
301
302
```bash
303
# Cron job
304
curl -X POST http://localhost:5000/scheduler/jobs \
305
-H "Content-Type: application/json" \
306
-d '{
307
"id": "daily_task",
308
"func": "tasks:daily_cleanup",
309
"trigger": "cron",
310
"hour": 2,
311
"minute": 0,
312
"name": "Daily Cleanup Task",
313
"misfire_grace_time": 300
314
}'
315
316
# Date job (one-time execution)
317
curl -X POST http://localhost:5000/scheduler/jobs \
318
-H "Content-Type: application/json" \
319
-d '{
320
"id": "delayed_task",
321
"func": "tasks:process_data",
322
"trigger": "date",
323
"run_date": "2024-12-25T10:00:00",
324
"args": ["data.json"],
325
"kwargs": {"format": "json"}
326
}'
327
```
328
329
## Response Formats
330
331
### Job Object Structure
332
333
```json
334
{
335
"id": "job_id",
336
"name": "Job Name",
337
"func": "module:function",
338
"args": [1, 2, 3],
339
"kwargs": {"key": "value"},
340
"trigger": "interval",
341
"seconds": 30,
342
"next_run_time": "2024-01-15T10:30:00.123456",
343
"misfire_grace_time": 60,
344
"max_instances": 1
345
}
346
```
347
348
### Scheduler Info Structure
349
350
```json
351
{
352
"current_host": "hostname.local",
353
"allowed_hosts": ["*"],
354
"running": true
355
}
356
```
357
358
### Error Response Structure
359
360
```json
361
{
362
"error_message": "Detailed error description"
363
}
364
```