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
• 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

Read the documentation for details. Upgrading from an earlier version? See 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"]

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 latest release. 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
RUN pip install --no-cache-dir -r 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.

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 pre-releases (e.g., vX.Y.Zrc1) create pre-releases and do not update latest.

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 Cloud & AAI. 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.