Flask Boilerplate

This is an minimal but opinionated boilerplate meant for building out simple REST APIs. It is primarily used at Hack4Impact UIUC. This app is written in Python 3.6 with Postgres 10 as the chosen data persistence. The default way to deploy it is with Heroku but you can deploy it with another service, like AWS, Google Cloud, or DigitalOcean with Gunicorn and Nginx, but instructions for that are not provided. Included are simple examples and instructions developing with or without Docker are provided. I've also written a blog post about using Docker based on this repository.

Documentation is located here. We use pipenv for dependency management, black for code formatting, and mypy for optional static typing.

Goal

The goal of this boilerplate is to allow developers to quickly write their API with code structured to best practices while giving them flexibility to easily add/change features. Here are the problems this is trying to solve:

Flask is too flexible. With Flask, you can write your application in any structure you like, even in one file. There are also a lot of different tutorials and guides providing different instructions & application structures to set up a Flask app with a database, confusing many newcomers about best practices.
Django and other Flask boilerplates are too heavy. Sometimes, I don't need a fully featured admin portal with Redis and an Email manager nor do I need templates. Many APIs and applications require the use of a database though. Thus, I've chosen Postgres because it is a battle-tested and reliable database used in many companies and we know that 99% of applications can easily be designed to use relational databases (especially the ones used at Hack4Impact).

Docs

Please Please PLEASE read the documentation if you don't understand something relevant to this boilerplate. Documentation is provided in the wiki page of this repository.

Usage

Here are some quickstart instructions, although I would look at the documentation for more details.

Then, install the python dependencies and run the server:

pipenv install
pipenv install --dev
pipenv run python manage.py runserver

Repository Contents

api/views/ - Holds files that define your endpoints
api/__init__.py - What is initially ran when you start your application
api/utils.py - utility functions and classes - explained here
api/core.py - includes core functionality including error handlers and logger
tests/ - Folder holding tests

Others

config.py - Provides Configuration for the application. There are two configurations: one for development and one for production using Heroku.
manage.py - Command line interface that allows you to perform common functions with a command
requirements.txt - A list of python package dependencies the application requires
runtime.txt & Procfile - configuration for Heroku
Dockerfile - instructions for Docker to build the Flask app
docker-compose.yml - config to setup this Flask app and a Database
migrations/ - Holds migration files – doesn't exist until you python manage.py db init if you decide to not use docker

MISC

If you're annoyed by the pycache files

find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf

Additional Documentation

Flask - Flask Documentation
Flask Tutorial - great tutorial. Many patterns used here were pulled from there.
Flask SQLAlchemy - the ORM for the database
Heroku - Deployment using Heroku
Learn Python - Learning Python3
Relational Databases - Designing a database schema
REST API - tips on making an API Restful
Docker Docs - Docker docs

Feel free to contact me for questions and contributions are welcome :)
tk2@illinois.edu

hack4impact-uiuc/flask-bootcamp-sp19