FOCA

An archetype for OpenAPI-based web services in Python, brought to you by ELIXIR On-Cloud. FOCA (Flask-OpenAPI-Connexion-Archetype) builds a Connexion app on Flask from your OpenAPI specifications and a single configuration file, so that you only write the controllers and the logic of your app. It provides:

• OpenAPI 2.x/3.x specifications, validated and routed by Connexion and modified on the fly;
• a validated, typed configuration, with environment-specific overlays;
• errors as problem details;
• bearer token validation for the OpenID Connect providers that you trust;
• access control with Casbin: policies on all operations, roles of users and groups, resource ownership and a permissions API;
• MongoDB databases, collections and indexes;
• background tasks with Celery and RabbitMQ;
• CORS and a GA4GH service info endpoint;
• Docker base images with SBOM and provenance attestations, and a Helm library chart for Kubernetes with a provenance attestation, all signed.

Read the documentation for the configuration, authentication, access control, the deployment with Docker and Helm, the utilities, the API reference and development. Upgrading from an earlier version? See Migrating to 0.17.0 (from 0.15 or earlier, first Migrating to 0.16.0, Migrating to 0.15.0 and Migrating to 0.14.0).

Why FOCA

FOCA's package has about 9,300 lines of code, tested by about 12,600 lines of tests, and its Helm library chart about 1,750 lines. Cloud Registry, for example, uses almost all of the package (all but the Celery factory and a database helper) and has about 2,200 lines of code of its own, plus about 9,000 lines of tests. Its own code is thus about a fifth of what it would be without FOCA, counting code only, and about a third, counting code and tests. Even if an app needed only half of FOCA's code, FOCA would still save it about 4,500 lines, plus their tests and the chart. (Lines of Python without blank lines and comments, docstrings included; FOCA 0.17.0 and Cloud Registry in October 2026.)

The savings add up with every app: if you maintain several OpenAPI-based apps, they all share the same authentication, access control, configuration, errors, images and Helm chart, and security fixes and upgrades are made once, in FOCA, instead of in every app.

Apps built with FOCA

App	Description
Cloud Registry	A registry of web services, implementing the GA4GH Service Registry API
proTES	A gateway for the GA4GH Task Execution Service (TES) API that federates TES instances

See also the dependents of FOCA on GitHub. Built an app with FOCA? Open a pull request that adds it to the table in README.md.

Quick start

Install the FOCA package (Python 3.11 to 3.15) with pip:

pip install foca

Write a configuration file that points to your OpenAPI specification and the module of its controllers, e.g., config.yaml:

api:
  specs:
    my-api:
      path: api/openapi.yaml
      add_operation_fields:
        x-openapi-router-controller: my_app.controllers

Then create and run your app:

from foca import Foca

app = Foca(config_file="config.yaml").create_app()  # Connexion app

if __name__ == "__main__":
    app.run()

See Getting started for a step-by-step guide and the Docker image, and the Petstore example app to see FOCA in action.

Contributing

Contributions are welcome! See CONTRIBUTING.md and Contributing in the documentation, and mind our code of conduct.