A better boilerplate for RESTful APIs using Flask.

If you have ever used Flask to build REST APIs, you'd know how cumbersome it can get. This repository aims to change that.

This repository:

1. Aims to fix common pain points with building REST APIs with Flask.
2. Uses pluggable views, blueprints, decorators and pydantic to modularize application and avoid repetition commonly associated with CRUD calls (DRY principle). See how fast and easy it is to write APIs using this boilerplate.
3. Doesn't use any of the Flask-RESTFul (Latest release: 2014), Flask-Restless (Latest release: 2016), or any similar spin-offs of Flask which eventually died out. Instead it relies only on core Flask. This has a huge advantage of always having the latest version of Flask for your application.

• Web framework: Flask
• ORM: SQLAlchemy
• Database: PostgresSQL
• Parsing/Validation: Pydantic
• Containerization: Docker
• Async-Task Queue: Celery
• Message-Broker: RabbitMQ
• WSGI Server: Gunicorn
• Reverse Proxy Server: NGINX
• Documentation: Swagger-UI

• Containerized Docker build
• Separate docker services for database (db), message-broker (celery-broker), API (web), and documentation (swagger-ui).
• Ability to run this API with a different database, or broker, or documentation service. As easy as editing docker-compose and .env files.
• Separate environments and configs for Development, Testing, and Production.
• RESTful API documentation via Swagger and visualization with Swagger UI.
• Easy to write different API versions.
• Authentication via JWT.
• Email Verification.
• OAuth for Github and Facebook.
• Parsing and Validation via Pydantic.
• Database entities integrated with SQLAlchemy.
• Tests covering each of the REST API services, with code coverage.

• Get Started
• Testing and Coverage
• RESTful endpoints
• Guide for extending this Boilerplate

• Docker
• Docker Compose
• Docker Machine
• Other dependencies are listed in requirements.txt and are installed automatically.

Get docker: https://docs.docker.com/get-docker/

Clone all the project from this repository and move to repository folder.

Rename .env.dev.sample file to .env.dev. All environment variables are set from this file.

Make sure you set the following environment variables:

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
FACEBOOK_CLIENT_ID
FACEBOOK_CLIENT_SECRET
MAIL_SERVER
MAIL_PORT
MAIL_USERNAME
MAIL_PASSWORD
MAIL_DEFAULT_SENDER

Build the images and run the containers.

docker-compose up --build

or if you want to run it in detached (background) mode:

docker-compose up -d --build

Make sure all containers are running:

docker-compose ps

web
db                                                      
broker
docs

Check swagger API documentation through http://localhost:8000. API is available under http://localhost:5000/v1. You can change the default ports in docker-compose.yml file.

Create all development db tables:

docker-compose exec web python manage.py create_db

Recreate all development db tables:

docker-compose exec web python manage.py recreate_db

Populate seed data into db:

docker-compose exec web python manage.py seed_db

Want to reset everything?

docker-compose down -v
docker-compose up --build

Finally test that everything works by executing the following curl command that tries to logged in using a default user created in the seed_db command: (default admin email: admin@arsal.me, password: password).

curl -X POST "http://0.0.0.0:5000/v1/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"email\":\"admin@arsal.me\",\"password\":\"password\"}"

You should get a response like this:

{
  "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzODEzMTUsImlhdCI6MTUyNzc4OTMxNSwic3ViIjoxfQ.Dzf017g5Qf9Mi24AH-0X3womGW2koTY3c3cCO5p1djE",
  "message": "Successfully logged in."
}

Run tests using:

docker-compose exec web python manage.py test

You should see an output like this:

...
...
Ensure encoding auth token works ... ok
test_model_user_passwords_are_random (test_model_user.TestUserModel)
Ensure passwords are randomly hashed ... ok
test_user_get (test_user_user.TestUserBlueprint)
Ensure get single user behaves correctly. ... ok

----------------------------------------------------------------------
Ran 80 tests in 13.335s

OK

Run coverage using:

docker-compose exec web python manage.py cov

Different roles: USER, ADMIN.

Endpoints implementation can be found under /project/api/v1/auth/core.py.

Endpoints implementation can be found under /project/api/v1/auth/social.py.

Endpoints implementation can be found under /project/api/v1/auth/email_verification.py.

Requires role: ADMIN

Endpoints implementation can be found under /project/api/v1/admin/users.py.

Requires role: USER

Endpoints implementation can be found under /project/api/v1/user/user.py.

For detailed documentation including request/response data, please check the Swagger-UI at http://localhost:8000.

Extending this boilerplate is very simple. Example: You need to add a new API called items which lets normal users CRUD on their items.

1. Create item database model in project/models.
2. Create items.py in api/v1/user/ folder.
   1. See this as an example of how-to.
   2. Create an ItemsAPI class and extend this class from BaseAPI and MethodView classes.
   3. Overwrite the CRUD methods inherited from BaseAPI. In most cases, you'll just need to use a one-liner to call the base class method with your validation model, and db class.
3. Create items.py in api/v1/validations/user/ folder.
   1. See this as an example of how-to.
   2. You will need knowledge of pydantic to write validation models.
4. Create a new test file test_user_items.py (convention for this project) in services/web/tests and write your tests.

In a nutshell, your request data is forwarded to BaseAPI, and for POST/PUT methods, you provide validation classes which map to attributes directly in database models. Any fields you provide in your validation classes (which already exist in DB models), are automatically mapped. Moreover, the data is also validated for its type, as well as any custom validators that you define.

For admins, you will follow the same procedure, but instead use the admin folder under api/v1 and api/v1/validations.

Feel free to nudge me if you need help. I'll also improve this writeup pretty soon.