FOCA (Flask-OpenAPI-Connexion-Archetype) is an opinionated archetype that enables fast development of OpenAPI-based HTTP API microservices in Flask, leveraging the excellent Connexion framework.
FOCA reduces the required boilerplate code to fire up your app to a bare minimum and allows you to focus on your application logic. It also avoids unnecessary code repetition and introduces cross-service consistency when developing multiple applications. Simply write a configuration file, pass it to FOCA and you're good to go!
Features:
- Validated, typed app configuration, with environment-specific overlays
- OpenAPI 2.x/3.x specifications, merged and modified on the fly
- Errors as problem details, with configurable media type
- Bearer token (JWT) validation for trusted OpenID Connect issuers
- Policy-based access control with Casbin, including a permissions API
- MongoDB databases, collections and indexes
- Background tasks with RabbitMQ & Celery
- Configurable CORS
- GA4GH service info served from the configuration
Read the documentation for details. Upgrading from an earlier version? See Migrating to 0.16.0 (from 0.14 or earlier, first Migrating to 0.15.0 and Migrating to 0.14.0).
(1) Install the FOCA package with pip:
pip install foca(2) Create a configuration file, e.g.:
api:
specs:
- path: api/openapi.yaml
add_operation_fields:
x-openapi-router-controller: my_app.controllers(3) Create and run your app:
from foca import Foca
app = Foca(config_file="config.yaml").create_app() # Connexion app
if __name__ == "__main__":
app.run()
Check out the Petstore example application
shipped with this repository to see FOCA in action! See Getting
started for a step-by-step guide.
FOCA images with all dependencies installed are published as
elixircloud/foca (built from
docker/Dockerfile), for use as base images of apps:
FROM elixircloud/foca:latest
COPY ./ /app
CMD ["python", "app.py"]python app.py starts Flask's development server, which is meant for local
development only. In production, run the app with a WSGI server such as
Gunicorn (see running in production).
Images of releases are tagged with the FOCA and Python versions (e.g.,
0.14.0-py3.12); the FOCA version alone (e.g., 0.14.0) tags the Python
3.13 image, and latest that of the highest stable release (not an alpha,
beta or release candidate). Images built from the dev branch are tagged
with their date and the Python version (e.g., 20261019-py3.13).
The image contains no build tools and runs as non-root user foca (UID
1000, group 0); /app and the home directory are writable by group 0,
so that the image also runs under arbitrary user IDs (e.g., on OpenShift).
To install system or Python packages in derived images, switch to root and
back:
USER root
COPY requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt
USER 1000This project is a community effort and lives off your contributions, be it in the form of bug reports, feature requests, discussions, or fixes and other code changes. Please refer to our organization's contributing guidelines if you are interested to contribute. Please mind the code of conduct for all interactions with the community.
Test coverage of foca is kept at 100%, which is enforced: coverage report
(and CI) fails below 100% (fail_under in pyproject.toml), and so do
Codecov's checks of the whole code and of the changes of a pull request
(codecov.yml). The tests marked mongodb need a MongoDB server on
localhost:12345:
pip install -e .[dev]
coverage run -m pytest
coverage report -mTo build the documentation locally, install the docs extra and run MkDocs:
pip install -e .[docs]
mkdocs serveThe project adopts semantic versioning. Currently the service is in beta stage, so the API may change without further notice.
The version is derived from git tags (via setuptools-scm)
and available as foca.__version__; builds between releases get
development versions (e.g., 0.14.1.dev3+g1a2b3c4).
Features and fixes are merged into dev. Branch main only ever moves
forward to commits on dev that are released. To release version X.Y.Z
from commit <sha> on dev, after CI passed for it:
git push origin <sha>:main # fails unless it is a fast-forward
git tag -s vX.Y.Z <sha> -m "vX.Y.Z"
git push origin vX.Y.ZPushing the tag triggers the release workflow, which
checks that the tagged commit is on main, publishes the distributions to
PyPI (after approval in the pypi environment), pushes Docker images
tagged X.Y.Z and latest, and creates a GitHub release with generated
notes. Tags of alpha, beta and release candidate versions (e.g.,
vX.Y.Zrc1) do not update latest. These and, until 1.0.0, all other
releases are GitHub pre-releases (never marked as the latest release).
The Helm library chart foca-common (charts/foca-common) is versioned
and released separately, from signed tags chart-vX.Y.Z; see releases of
the library chart.
This project is covered by the Apache License 2.0 also shipped with this repository.
The project is a collaborative effort under the umbrella of ELIXIR On-Cloud. Follow the link to get in touch with us via chat or email. Please mention the name of this service for any inquiry, proposal, question etc.
