REST API
supvisorsflask is a Supvisors Flask-RESTX application that is added to the BINDIR
.
It exposes the Supervisor and Supvisors XML-RPC API through a REST API.
Note
An exception however: the Supervisor system.multicall
XML-RPC has not been implemented.
Starting the Flask-RESTX application
The program supvisorsflask requires 2 main information to work:
the URL of the Supervisor instance to address the XML-RPCs,
the URL of the Flask web server to which the REST API will be exposed.
If supvisorsflask is spawned by Supervisor, it naturally gets the URL of the Supervisor instance through
the SUPERVISOR_SERVER_URL
environment variable. Otherwise, this URL must be passed using the -u SUPERVISOR_URL
option.
Default values for HOST
and PORT
are the Flask default values, i.e. the application will run the web server
on http://127.0.0.1:5000
.
[bash] > supvisorsflask --help
usage: supvisorsflask [--help] -u SUPERVISOR_URL [-h HOST] [-p PORT] [-d]
Start a Flask application to interact with Supvisors
optional arguments:
--help show this help message and exit
-u SUPERVISOR_URL, --supervisor_url SUPERVISOR_URL
the Supervisor URL, required if supvisorsflask is not
spawned by Supervisor
-h HOST, --host HOST the Flask server IP address
-p PORT, --port PORT the Flask server port number
-d, --debug the Flask Debug mode
Using the REST API
The aim of the present documentation is not to be a REST API tutorial. So here follows just a few usage examples with curl and python. Of course, many other programming languages will provide an API to perform such requests.
curl commands
A first possibility is to use curl commands in a shell.
[bash] > curl -X 'GET' 'http://localhost:5000/supvisors/supvisors_state' -H 'accept: application/json'
{"fsm_statecode": 3, "fsm_statename": "OPERATION", "starting_jobs": [], "stopping_jobs": []}
[bash] > curl -X 'POST' \
'http://127.0.0.1:5000/supvisors/start_process/CONFIG/my_movies%3Aconverter_00?extra_args=-x%202&wait=false' \
-H 'accept: application/json'
true
Supervisor XML-RPC exceptions will return a payload including the fault message and code.
[bash] > curl -X 'GET' 'http://localhost:5000/supvisors/application_info/dummy' -H 'accept: application/json'
{"message": "BAD_NAME: application dummy unknown to Supvisors", "code": 10}
[bash] > curl -X 'POST' \
'http://127.0.0.1:5000/supvisors/start_process/CONFIG/my_movies%3Aconverter_00?extra_args=-x%202&wait=false' \
-H 'accept: application/json'
{"message": "ALREADY_STARTED: my_movies:converter_00", "code": 60}
Python requests
Here is a possibility using the Python module Requests. All results are a JSON string.
>>> import json, requests
>>> res = requests.get('http://localhost:5000/supvisors/supvisors_state')
>>> print(res.text)
{"fsm_statecode": 3, "fsm_statename": "OPERATION", "starting_jobs": [], "stopping_jobs": []}
>>> print(json.loads(res.text))
{'fsm_statecode': 3, 'fsm_statename': 'OPERATION', 'starting_jobs': [], 'stopping_jobs': []}
>>> res = requests.post(f'http://localhost:5000/supvisors/start_process/LESS_LOADED/my_movies%3Aconverter_01?extra_args=-x%201&wait=true')
>>> print(json.loads(res.text))
{'message': 'ABNORMAL_TERMINATION: my_movies:converter_01', 'code': 40}
Using the Swagger UI
An interest in using Flask-RESTX over Flask is to benefit from a documented Web UI when connecting a browser to the URL defined above.
The Web UI allows to test the REST API proposed.