Make API configurable via the setup utility

Fix some small bugs in the setup utility
Improve documentation on the API.
main
Dimitri Huisman 2 years ago
parent cc6c808838
commit d6e7314f05
No known key found for this signature in database

@ -74,7 +74,6 @@ def create_app_from_config(config):
app.register_blueprint(ui.ui, url_prefix=app.config['WEB_ADMIN'])
app.register_blueprint(internal.internal, url_prefix='/internal')
app.register_blueprint(sso.sso, url_prefix='/sso')
if app.config.get('API_TOKEN'):
api.register(app, web_api_root=app.config.get('WEB_API'))
return app

@ -8,6 +8,7 @@ def register(app, web_api_root):
# register api bluprint(s)
apidoc.apidoc.url_prefix = f'{web_api_root}/v{int(APIv1.VERSION)}'
APIv1.api_token = app.config['API_TOKEN']
if app.config['API_TOKEN'] != '':
app.register_blueprint(APIv1.blueprint, url_prefix=f'{web_api_root}/v{int(APIv1.VERSION)}')
# add redirect to current api version
@ -22,3 +23,10 @@ def register(app, web_api_root):
app.config.SWAGGER_UI_OPERATION_ID = True
app.config.SWAGGER_UI_REQUEST_DURATION = True
app.config.RESTX_MASK_SWAGGER = False
else:
api = Blueprint('api', __name__)
@api.route('/', defaults={'path': ''})
@api.route('/<path:path>')
def api_token_missing(path):
return "<p>Error: API_TOKEN is not configured</p>", 500
app.register_blueprint(api, url_prefix=f'{web_api_root}')

@ -5,21 +5,22 @@ Mailu offers a RESTful API for changing the Mailu configuration.
Anything that can be configured via the Mailu web administration interface,
can also be configured via the API.
The Mailu API is disabled by default. It can be enabled and configured via
the settings:
The Mailu API can be configured via the setup utility (setup.mailu.io).
It can also be manually configured via mailu.env:
* ``API``
* ``WEB_API``
* ``API_TOKEN``
* ``API`` - Expose the API interface (value: true, false)
* ``WEB_API`` - Path to the API interface
* ``API_TOKEN`` - API token for authentication
For more information see the section :ref:`Advanced configuration <advanced_settings>`
in the configuration reference.
For more information refer to the detailed descriptions in the
:ref:`configuration reference <advanced_settings>`.
Swagger.json
------------
The swagger.json file can be retrieved via: https://myserver/api/v1/swagger.json.
The swagger.json file can be retrieved via: https://myserver/api/v1/swagger.json
(WEB_API=/api)
The swagger.json file can be consumed in programs such as Postman for generating all API calls.
@ -28,4 +29,5 @@ In-built SwaggerUI
The Mailu API comes with an in-built SwaggerUI. It is a web client that allows
anyone to visualize and interact with the Mailu API.
It is accessible via the URL: https://myserver/api/v1/swaggerui
Assuming ``/api`` is configured as value for ``WEB_API``, it
is accessible via the URL: https://myserver/api/

@ -140,13 +140,15 @@ Web settings
- ``WEB_WEBMAIL`` contains the path to the Web email client.
- ``WEB_API`` contains the path to the RESTful API.
- ``WEBROOT_REDIRECT`` redirects all non-found queries to the set path.
An empty ``WEBROOT_REDIRECT`` value disables redirecting and enables
classic behavior of a 404 result when not found.
Alternatively, ``WEBROOT_REDIRECT`` can be set to ``none`` if you
are using an Nginx override for ``location /``.
All three options need a leading slash (``/``) to work.
All four options need a leading slash (``/``) to work.
.. note:: ``WEBROOT_REDIRECT`` has to point to a valid path on the webserver.
This means it cannot point to any services which are not enabled.
@ -203,13 +205,9 @@ Depending on your particular deployment you most probably will want to change th
Advanced settings
-----------------
The ``API`` (default: False) setting controls if the API endpoint is reachable.
The ``WEB_API`` (default: /api) setting configures the endpoint that the API
listens on publicly&interally. The path must always start with a leading slash.
The ``API_TOKEN`` (default: None) enables the API endpoint. This token must be
passed as request header to the API as authentication token.
The ``API_TOKEN`` (default: None) configures the authentication token.
This token must be passed as request header to the API as authentication token.
This is a mandatory setting for using the RESTful API.
The ``CREDENTIAL_ROUNDS`` (default: 12) setting is the number of rounds used by the
password hashing scheme. The number of rounds can be reduced in case faster

@ -52,6 +52,9 @@ ADMIN={{ admin_enabled or 'false' }}
# Choose which webmail to run if any (values: roundcube, snappymail, none)
WEBMAIL={{ webmail_type }}
# Expose the API interface (value: true, false)
API={{ api_enabled or 'false' }}
# Dav server implementation (value: radicale, none)
WEBDAV={{ webdav_enabled or 'none' }}
@ -131,6 +134,9 @@ WEB_WEBMAIL=/
WEB_WEBMAIL={{ webmail_path }}
{% endif %}
# Path to the API interface if enabled
WEB_API={{ api_path }}
# Website name
SITENAME={{ site_name }}
@ -182,6 +188,10 @@ TZ=Etc/UTC
# Default spam threshold used for new users
DEFAULT_SPAM_THRESHOLD=80
# API token required for authenticating to the RESTful API.
# This is a mandatory setting for using the RESTful API.
API_TOKEN={{ api_token }}
###################################
# Database settings
###################################

@ -1,18 +1,18 @@
$(document).ready(function() {
if ($("#webmail").val() == 'none') {
$("#webmail_path").hide();
$("#webmail_path").attr("value", "");
$("#webmail_path").val("");
} else {
$("#webmail_path").show();
$("#webmail_path").attr("value", "/webmail");
$("#webmail_path").val("/webmail");
}
$("#webmail").click(function() {
if (this.value == 'none') {
$("#webmail_path").hide();
$("#webmail_path").attr("value", "");
$("#webmail_path").val("");
} else {
$("#webmail_path").show();
$("#webmail_path").attr("value", "/webmail");
$("#webmail_path").val("/webmail");
}
});
});
@ -20,15 +20,43 @@ $(document).ready(function() {
$(document).ready(function() {
if ($('#admin').prop('checked')) {
$("#admin_path").show();
$("#admin_path").attr("value", "/admin");
$("#admin_path").val("/admin");
}
$("#admin").change(function() {
if ($(this).is(":checked")) {
$("#admin_path").show();
$("#admin_path").attr("value", "/admin");
$("#admin_path").val("/admin");
} else {
$("#admin_path").hide();
$("#admin_path").attr("value", "");
$("#admin_path").val("");
}
});
});
$(document).ready(function() {
if ($('#api').prop('checked')) {
$("#api_path").show();
$("#api_path").val("/api")
$("#api_token").show();
$("#api_token").prop('required',true);
$("#api_token").val("");
$("#api_token_label").show();
}
$("#api").change(function() {
if ($(this).is(":checked")) {
$("#api_path").show();
$("#api_path").val("/api");
$("#api_token").show();
$("#api_token").prop('required',true);
$("#api_token").val("")
$("#api_token_label").show();
} else {
$("#api_path").hide();
$("#api_path").val("/api")
$("#api_token").hide();
$("#api_token").prop('required',false);
$("#api_token").val("");
$("#api_token_label").hide();
}
});
});

@ -87,6 +87,19 @@ manage your email domains, users, etc.</p>
<input class="form-control" type="text" name="admin_path" id="admin_path" style="display: none">
</div>
<p>The API interface is a RESTful API for changing the Mailu configuration.
Anything that can be configured via the Mailu web administration interface,
can also be configured via the RESTful API. For enabling the API, an API token must be configured.
It is not possible to use the API without an API token.</p>
<div class="form-group">
<input type="checkbox" name="api_enabled" value="true" id="api" checked>
<label>Enable the API (and path to the API)</label>
<input class="form-control" type="text" name="api_path" id="api_path" style="display: none">
<label name="api_token_label" id="api_token_label">API token</label>
<input class="form-control" type="text" name="api_token" id="api_token" style="display: none">
</div>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<script type="text/javascript" src="{{ url_for('static', filename='render.js') }}"></script>

Loading…
Cancel
Save