Develop Flask microservices quickly!

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).

Usage

(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.

Docker image

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 1000

Contributing

This 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 -m

To build the documentation locally, install the docs extra and run MkDocs:

pip install -e .[docs]
mkdocs serve

Versioning

The 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).

Releasing

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.Z

Pushing 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.

License

This project is covered by the Apache License 2.0 also shipped with this repository.

Contact

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.