Quickly develop Flask microservices!

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!

Currently supported features:

• Manage app configuration
• Handle exceptions
• Register OpenAPI 2.x/3.x specifications
• Protect endpoints via JWT validation
• Register MongoDB collections
• Run asynchronous tasks via RabbitMQ & Celery
• CORS support

Check the API docs for further details.

(1) Install the FOCA package with pip:

pip install foca

(2) Create a configuration file.

(3) Import the FOCA main function foca() and pass your config:

from foca import foca

app = foca("path/to/my/app/config.yaml")  # returns a Connexion app instance

(4) Start your Flask app as usual.

Check out the Petstore example application shipped with this repository to see FOCA in action!

In order to use FOCA functionalities, you must create a YAML configuration file that includes keyword sections reserved by FOCA.

In order to get you started writing your own app configuration, you can copy the annotated template shipped with this repository and modify it.

For further information on the writing FOCA configuration files, read on.

For example, if you want to register a MongoDB database collection, your configuration file must include the top-level database keyword section, e.g.:

db:
  host: mongodb
  port: 27017
  dbs:
    myDb:
      collections:
        myCollection:
          indexes:
            - keys:
                id: 1
              options:
                'unique': True

This config would create a MongoDB database myDb with collection myCollection in your database server. The collection would be indexed by key id, which is required to be unique. To register another collection, simply add another named CollectionConfig object as a child to collections, e.g., yourCollection, with its own indexes etc.

If you do not want to register a database collection, you can simply omit that section, but note that once a section is included, it MUST adhere to the corresponding model described in the API documentation.

Keywords reserved by FOCA include the following (exhaustive; follow links to corresponding models):

• api
• db
• exceptions
• jobs
• log
• security
• server

Any values passed to reserved keywords are automatically validated and a corresponding informative exception will be raised whenever a value does not adhere to the corresponding model.

Any top-level sections that are not listed above will simply be passed to the app instance returned by the foca() function. All configuration parameters, reserved by FOCA and any custom ones, will be available in the application context as attributes of current_app.config['FOCA'].

Apart from the annotated template, you can also check out the configuration file of the Petstore app for another example.

Or why not explore apps that already use FOCA?

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.

The project adopts semantic versioning. Currently the service is in beta stage, so the API may change without further notice.

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