A python microservice framework


Quick start
Project files
OpenAPI specification
API objects
Server code
Deployment pipeline
Docker packaging
JWT authentication
Error handling
Asynchronous execution
Database serialisation


pymacaron is a python microservice framework based on Flask, OpenAPI, docker, AWS or GCP, Celery and Bravado-Core.

PyMacaron aims at abstracting away all the scaffholding of setting up a Flask microservice, its routes, its deployment pipeline, etc. The only code you should have to write are the the python methods bound to every API endpoint.

Core features

OpenAPI specifications

At the core of pymacaron lies your API definitions, in the form of yaml files following the OpenAPI/swagger standard.

Those API definitions describe every endpoint in your REST/JSON APIs: which data they accept as parameters and what data they return. An OpenAPI specification also describes every data model used in your API.

Self-defined routes

A PyMacaron server is basically a Flask server whose routes are automatically added at start time, based on the endpoints defined in your OpenAPI/swagger files.

pymacaron-core extends the standard OpenAPI format to let you bind API endpoints to python methods and add JWT-based authentication to chosen endpoints.

More details here.

Endpoints that take and return objects

PyMacaron transparently converts the json body of a request into a PyMacaron Model instance, basically a python object with getters, setters and convenient builtin methods.

This object is passed to the python method bound to the API endpoint, together with other query parameters, and this method later returns an other PyMacaron Model instance, that will be serialized to json and returned to the caller.

Those objects are defined in your OpenAPI specification, in the form of ‘schema objects’.

PyMacaron also extends the OpenAPI standard to let you assign a parent class to schema objects, or to make them serializable to/from a database.

More details here.

JWT authentication

You can add authentication around API endpoints in a PyMacaron microservice by using PyMacaron’s built-in support for JWT tokens. More details here.

Pluggable features

Core features

By itself, pymacaron only lets you build a REST microservice and run it as a local server. Pymacaron uses pymacaron-core to take an OpenAPI yaml specification and start a Flask app implementing it. Pymacaron-core is in fact a thin layer on top of bravado-core.

Other pymacaron features are available as plugins:

Deployment pipeline

PyMacaron microservices come with a deployment pipeline that packages the service as a docker image and deploys it to Amazon Beanstalk, GKE or Google Cloud Run.

Asynchronous task execution

pymacaron-async adds support for asynchronous task execution to your API endpoints, based on Celery and Redis.

More details here.

Blackbox testing framework

pymacaron-unit is a unittesting library to write blackbox tests targeting your API endpoints.

More details here.

Object persistence

Object persistence is achieved by letting PyMacaron models inherit from a class that handles persistence and serialisation. pymacaron-dynamodb does that between Amazon’s DynamoDB and PyMacaron models.