cookiecutter-flask-restful

Cookiecutter template for flask restful, including blueprints, application factory, and more

Introduction

This cookie cutter is a very simple boilerplate for starting a REST api using Flask, flask-restful, marshmallow, SQLAlchemy and jwt. It comes with basic project structure and configuration, including blueprints, application factory and basics unit tests.

Features

• Simple flask application using application factory, blueprints
• Flask command line interface integration
• Simple cli implementation with basics commands (init, run, etc.)
• Flask Migrate included in entry point
• Authentication using Flask-JWT-Extended including access token and refresh token management
• Simple pagination utils
• Unit tests using pytest and factoryboy
• Configuration override using environment variable

Used packages :

• Flask
• Flask-RESTful
• Flask-Migrate
• Flask-SQLAlchemy
• Flask-Marshmallow
• Flask-JWT-Extended
• marshmallow-sqlalchemy
• passlib
• tox
• pytest
• factoryboy
• dotenv

Usage

Installation

For the example, let's say you named your app myapi and your project myproject

Once project started with cookiecutter, you can install it using pip :

cd myproject
pip install -r requirements.txt
pip install -e .

You have now access to cli commands and you can init your project

myapi init

To list all commands

myapi --help

Authentication

To access protected resources, you will need an access token. You can generate an access and a refresh token using /auth/login endpoint, example using curl

curl -X POST -H "Content-Type: application/json" -d '{"username": "admin", "password": "admin"}' http://localhost:5000/auth/login

This will return something like this

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDQ0MSwiZnJlc2giOmZhbHNlLCJqdGkiOiI2OTg0MjZiYi00ZjJjLTQ5MWItYjE5YS0zZTEzYjU3MzFhMTYiLCJuYmYiOjE1MTAwMDA0NDEsImV4cCI6MTUxMDAwMTM0MX0.P-USaEIs35CSVKyEow5UeXWzTQTrrPS_YjVsltqi7N4", 
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNTEwMDAwNDQxLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6IjRmMjgxOTQxLTlmMWYtNGNiNi05YmI1LWI1ZjZhMjRjMmU0ZSIsIm5iZiI6MTUxMDAwMDQ0MSwiZXhwIjoxNTEyNTkyNDQxfQ.SJPsFPgWpZqZpHTc4L5lG_4aEKXVVpLLSW1LO7g4iU0"
}

You can use access_token to access protected endpoints :

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDQ0MSwiZnJlc2giOmZhbHNlLCJqdGkiOiI2OTg0MjZiYi00ZjJjLTQ5MWItYjE5YS0zZTEzYjU3MzFhMTYiLCJuYmYiOjE1MTAwMDA0NDEsImV4cCI6MTUxMDAwMTM0MX0.P-USaEIs35CSVKyEow5UeXWzTQTrrPS_YjVsltqi7N4" http://127.0.0.1:5000/api/v1/users

You can use refresh token to retreive a new access_token using the endpoint /auth/refresh

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNTEwMDAwNDQxLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6IjRmMjgxOTQxLTlmMWYtNGNiNi05YmI1LWI1ZjZhMjRjMmU0ZSIsIm5iZiI6MTUxMDAwMDQ0MSwiZXhwIjoxNTEyNTkyNDQxfQ.SJPsFPgWpZqZpHTc4L5lG_4aEKXVVpLLSW1LO7g4iU0" http://127.0.0.1:5000/auth/refresh

this will only return a new access token

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDYxOCwiZnJlc2giOmZhbHNlLCJqdGkiOiIzODcxMzg4Ni0zNGJjLTRhOWQtYmFlYS04MmZiNmQwZjEyNjAiLCJuYmYiOjE1MTAwMDA2MTgsImV4cCI6MTUxMDAwMTUxOH0.cHuNf-GxVFJnUZ_k9ycoMMb-zvZ10Y4qbrW8WkXdlpw"
}

Running tests

Simplest way to run tests is to use tox, it will create a virtualenv for tests, install all dependencies and run pytest

tox

But you can also run pytest manually, you just need to install tests dependencies before

pip install pytest pytest-runner pytest-flask pytest-factoryboy factory_boy
pytest

Running with gunicorn

This project provide a simple wsgi entry point to run gunicorn or uwsgi for example.

For gunicorn you only need to run the following commands

pip install gunicorn
gunicorn myapi.wsgi:app

And that's it ! Gunicorn is running on port 8000

Running with uwsgi

Pretty much the same as gunicorn here

pip install uwsgi
uwsgi --http 127.0.0.1:5000 --module myapi.wsgi:app

And that's it ! Uwsgi is running on port 5000

Using Flask CLI

This cookiecutter is fully compatible with default flask CLI and use a .flaskenv file to set correct env variables to bind the application factory. Note that we also set FLASK_ENV to development to enable debugger.

Using Celery

This cookiecutter has an optional Celery integration that let you choose if you want to use it or not in your project. If you choose to use Celery, additionnal code and files will be generated to get started with it.

This code will include a dummy task located in yourproject/yourapp/tasks/example.py that only return "OK" and a celery_app file used to your celery workers.

Running celery workers

In your project path, once dependencies are installed, you can just run

celery worker -A myapi.celery_app:app --loglevel=info

If you have updated your configuration for broker / result backend your workers should start and you should see the example task

[tasks]
  . myapi.tasks.example.dummy_task

Running a task

To run a task you can either import it and call it

>>> from myapi.tasks.example import dummy_task
>>> result = dummy_task.delay()
>>> result.get()
'OK'

Or use the celery extension

>>> from myapi.extensions import celery
>>> celery.send_task('myapi.tasks.example.dummy_task').get()
'OK'