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 or Zeit now 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 black for code formatting, and mypy for optional static typing.
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).
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. I've also added comments with links to specific Flask Documentation to explain certain design choices and/or a specific Flask API (ex: test clients).
Here are some quickstart instructions, although I would look at the documentation for more details.
First start a postgres docker container and persist the data with a volume flask-app-db
:
docker run -e POSTGRES_USER=testusr -e POSTGRES_PASSWORD=password -e POSTGRES_DB=testdb -p 5432:5432 -v flask-app-db:/var/lib/postgresql/data -d postgres:10
Another option is to create a postgres instance on a cloud service like elephantsql and connect it to this app. Remember to change the postgres url and don't hard code it in!
Then, start your virtual environment
$ pip3 install virtualenv
$ virtualenv venv
$ source venv/bin/activate
Now, install the python dependencies and run the server:
(venv) $ pip install -r requirements.txt
(venv) $ pip install -r requirements-dev.txt
(venv) $ python manage.py recreate_db
(venv) $ python manage.py runserver
To exit the virtual environment:
(venv) $ deactivate
$
For ease of setup, I have hard-coded postgres URLs for development and docker configurations. If you are using a separate postgres instance as mentioned above, do not hardcode the postgres url including the credentials to your code. Instead, create a file called creds.ini
in the same directory level as manage.py
and write something like this:
[pg_creds]
pg_url = postgresql://testusr:[email protected]:5432/testdb
For production, you should do something similar with the flask SECRET_KEY
.
You may use Heroku and the instructions are defined in the wiki page. I prefer Zeit now for their easy docker serverless deployments. To deploy, you must have the now cli and then run:
now -e DATABASE_URL=your_postgres_url
Note that you will need a postgres instance somewhere. Remember to run python manage.py recreate_db
to initialize all of the tables in the beginning! You may also use now secrets and put them
into the the optional zeit now config file now.json
.
api/views/
- Holds files that define your endpointsapi/models/
- Holds files that defines your database schemaapi/__init__.py
- What is initially ran when you start your applicationapi/utils.py
- utility functions and classes - explained hereapi/core.py
- includes core functionality including error handlers and loggerapi/wsgi.py
- app reference for gunicorntests/
- Folder holding tests
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 commandrequirements.txt
- A list of python package dependencies the application requiresruntime.txt
&Procfile
- configuration for HerokuDockerfile
- instructions for Docker to build the Flask appdocker-compose.yml
- config to setup this Flask app and a Databasemigrations/
- Holds migration files โ doesn't exist until youpython manage.py db init
if you decide to not use docker
If you're annoyed by the pycache files
find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf
- 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 :)
[email protected]