Structuring a Flask-RESTPlus Web Service for Production Builds

Image credit –

In this guide I’ll show you a step by step approach for structuring a Flask RESTPlus web application for testing, development and production environments. I will be using a Linux based OS (Ubuntu), but most of the steps can be replicated on Windows and Mac.

Before continuing with this guide, you should have a basic understanding of the Python programming language and the Flask micro framework. If you are not familiar with those, I recommend taking a look at an introductory article – How to use Python and Flask to build a web app.

How this guide is structured

This guide is divided into the following parts:

  • Features
  • What is Flask-RESTPlus?
  • Setup and Installation
  • Project Setup and Organization
  • Configuration Settings
  • Flask Script
  • Database Models and Migration
  • Testing
  • Configuration
  • User Operations
  • Security and Authentication
  • Route protection and Authorization
  • Extra tips
  • Extending the App & Conclusion


We’ll be using the following features and extensions within our project.

  • Flask-Bcrypt: A Flask extension that provides bcrypt hashing utilities for your application.
  • Flask-Migrate: An extension that handles SQLAlchemy database migrations for Flask applications using Alembic. The database operations are made available through the Flask command-line interface or through the Flask-Script extension.
  • Flask-SQLAlchemy: An extension for Flask that adds support for SQLAlchemy to your application.
  • PyJWT: A Python library which allows you to encode and decode JSON Web Tokens (JWT). JWT is an open, industry-standard (RFC 7519) for representing claims securely between two parties.
  • Flask-Script: An extension that provides support for writing external scripts in Flask and other command-line tasks that belong outside the web application itself.
  • Namespaces (Blueprints)
  • Flask-restplus
  • UnitTest

What is Flask-RESTPlus?

Flask-RESTPlus is an extension for Flask that adds support for quickly building REST APIs. Flask-RESTPlus encourages best practices with minimal setup. It provides a coherent collection of decorators and tools to describe your API and expose its documentation properly (using Swagger).

Setup and Installation

Check if you have pip installed, by typing the command pip –version into the Terminal , then press Enter.

pip --version

If the terminal responds with the version number, this means that pip is installed, so go to the next step, otherwise install pip or using the Linux package manager, run the command below on the terminal and press enter. Choose either the Python 2.x OR 3.x version.

  • Python 2.x
sudo apt-get install python-pip
  • Python 3.x
sudo apt-get install python3-pip

Set up virtual environment and virtual environment wrapper (you only need one of these, depending on the version installed above):

sudo pip install virtualenv
sudo pip3 install virtualenvwrapper

Follow this link for a complete setup of virtual environment wrapper.

Create a new environment and activate it by executing the following command on the terminal:

mkproject name_of_your_project

Project Setup and Organization

I will be using a functional structure to organize the files of the project by what they do. In a functional structure, templates are grouped together in one directory, static files in another and views in a third.

In the project directory, create a new package called app. Inside app, create two packages main and test. Your directory structure should look similar to the one below.

├── app
│ ├──
│ ├── main
│ │ └──
│ └── test
│ └──
└── requirements.txt

We are going to use a functional structure to modularize our application.
Inside the main package, create three more packages namely: controller, service and model. The model package will contain all of our database models while the service package will contain all the business logic of our application and finally the controller package will contain all our application endpoints. The tree structure should now look as follows:

├── app
│ ├──
│ ├── main
│ │ ├── controller
│ │ │ └──
│ │ ├──
│ │ ├── model
│ │ │ └──
│ │ └── service
│ │ └──
│ └── test
│ └──
└── requirements.txt

Now lets install the required packages. Make sure the virtual environment you created is activated and run the following commands on the terminal:

pip install flask-bcrypt
pip install flask-restplus
pip install Flask-Migrate
pip install pyjwt
pip install Flask-Script
pip install flask_testing

Create or update the requirements.txt file by running the command:

pip freeze > requirements.txt

The generated requirements.txt file should look similar to the one below:


Configuration Settings

In the main package create a file called with the following content:

The configuration file contains three environment setup classes which includes testing, development, and production.

We will be using the application factory pattern for creating our Flask object. This pattern is most useful for creating multiple instances of our application with different settings. This facilitates the ease at which we switch between our testing, development and production environment by calling the create_app function with the required parameter.

In the file inside the main package, enter the following lines of code:

Flask Script

Now let’s create our application entry point. In the root directory of the project, create a file called with the following content:

The above code within does the following:

  • line 4 and 5 imports the migrate and manager modules respectively (we will be using the migrate command soon).
  • line 9 calls the create_app function we created initially to create the application instance with the required parameter from the environment variable which can be either of the following – dev, prod, test. If none is set in the environment variable, the default dev is used.
  • line 13 and 15 instantiates the manager and migrate classes by passing the app instance to their respective constructors.
  • In line 17,we pass the db and MigrateCommandinstances to the add_command interface of the managerto expose all the database migration commands through Flask-Script.
  • line 20 and 25 marks the two functions as executable from the command line.

Flask-Migrate exposes two classes, Migrate and MigrateCommand. The Migrateclass contains all the functionality of the extension. The MigrateCommand class is only used when it is desired to expose database migration commands through the Flask-Script extension.

At this point, we can test the application by running the command below in the project root directory.

python run

If everything is okay, you should see something like this:

Database Models and Migration

Now let’s create our models. We will be using the db instance of the sqlalchemy to create our models.

The db instance contains all the functions and helpers from both sqlalchemy and sqlalchemy.orm and it provides a class called Model that is a declarative base which can be used to declare models.

In the model package, create a file called with the following content:

The above code within does the following:

  • line 3: The user class inherits from db.Model class which declares the class as a model for sqlalchemy.
  • line 7 through 13 creates the required columns for the user table.
  • line 21 is a setter for the field password_hash and it uses flask-bcrypt to generate a hash using the provided password.
  • line 24 compares a given password with already savedpassword_hash.

Now to generate the database table from the user model we just created, we will use migrateCommand through the manager interface. For managerto detect our models, we will have to import theuser model by adding below code to file:

from app.main.model import user

Now we can proceed to perform the migration by running the following commands on the project root directory:

  1. Initiate a migration folder using init command for alembic to perform the migrations.
python db init

2. Create a migration script from the detected changes in the model using the migrate command. This doesn’t affect the database yet.

python db migrate --message 'initial database migration'

3. Apply the migration script to the database by using the upgrade command

python db upgrade

If everything runs successfully, you should have a new sqlLite database
flask_boilerplate_main.db file generated inside the main package.

Each time the database model changes, repeat the migrate and upgrade commands



To be sure the setup for our environment configuration is working, let’s write a couple of tests for it.

Create a file called in the test package with the content below:

Run the test using the command below:

python test

You should get the following output:

User Operations

Now let’s work on the following user related operations:

  • creating a new user
  • getting a registered user with his public_id
  • getting all registered users.

User Service class: This class handles all the logic relating to the user model.
In the service package, create a new file with the following content:

The above code within does the following:

  • line 8 through 29 creates a new user by first checking if the user already exists; it returns a success response_object if the user doesn’t exist else it returns an error code 409 and a failure response_object.
  • line 33 and 37 return a list of all registered users and a user object by providing the public_id respectively.
  • line 40 to 42 commits the changes to database.

No need to use jsonify for formatting an object to JSON, Flask-restplus does it automatically

In the main package, create a new package called util . This package will contain all the necessary utilities we might need in our application.

In the util package, create a new file As the name implies, the data transfer object (DTO) will be responsible for carrying data between processes. In our own case, it will be used for marshaling data for our API calls. We will understand this better as we proceed.

The above code within does the following:

  • line 5 creates a new namespace for user related operations. Flask-RESTPlus provides a way to use almost the same pattern as Blueprint. The main idea is to split your app into reusable namespaces. A namespace module will contain models and resources declaration.
  • line 6 creates a new user dto through the model interface provided by the api namespace in line 5.

User Controller: The user controller class handles all the incoming HTTP requests relating to the user .

Under the controller package, create a new file called with the following content:

line 1 through 8 imports all the required resources for the user controller.
We defined two concrete classes in our user controller which are userList and user. These two classes extends the abstract flask-restplus resource.

Concrete resources should extend from this class and expose methods for each supported HTTP method. If a resource is invoked with an unsupported HTTP method, the API will return a response with status 405 Method Not Allowed. Otherwise the appropriate method is called and passed all arguments from the URL rule used when adding the resource to an API instance.

The api namespace in line 7 above provides the controller with several decorators which includes but is not limited to the following:

  • api.route: A decorator to route resources
  • api.marshal_with: A decorator specifying the fields to use for serialization (This is where we use the userDto we created earlier)
  • api.marshal_list_with: A shortcut decorator for marshal_with above with as_list = True
  • api.doc: A decorator to add some api documentation to the decorated object
  • api.response: A decorator to specify one of the expected responses
  • api.expect: A decorator to Specify the expected input model ( we still use the userDto for the expected input)
  • api.param: A decorator to specify one of the expected parameters

We have now defined our namespace with the user controller. Now its time to add it to the application entry point.

In the file of app package, enter the following:

The above code within does the following:

  • In line 8, we create a blueprint instance by passing name and import_name. API is the main entry point for the application resources and hence needs to be initialized with the blueprint in line 10.
  • In line 16 , we add the user namespace user_ns to the list of namespaces in the API instance.

We have now defined our blueprint. It’s time to register it on our Flask app.
Update by importing blueprint and registering it with the Flask application instance.

from app import blueprint
app = create_app(os.getenv('BOILERPLATE_ENV') or 'dev')

We can now test our application to see that everything is working fine.

python run

Now open the URL in your browser. You should see the swagger documentation.

Let’s test the create new user endpoint using the swagger testing functionality.

You should get the following response

Security and Authentication

Let’s create a model blacklistToken for storing blacklisted tokens. In the models package, create a file with the following content

Lets not forget to migrate the changes to take effect on our database.
Import the blacklist class in

from app.main.model import blacklist

Run the migrate and upgrade commands

python db migrate --message 'add blacklist table'
python db upgrade

Next create in the service package with the following content for blacklisting a token

Update the user model with two static methods for encoding and decoding tokens. Add the following imports:

import datetime
import jwt
from app.main.model.blacklist import BlacklistToken
from ..config import key
  • Encoding

  • Decoding: Blacklisted token, expired token and invalid token are taken into consideration while decoding the authentication token.

Now let’s write a test for the user model to ensure that our encode and decode functions are working properly.

In the test package, create file with the following content

The BaseTestCase sets up our test environment ready before and after every test case that extends it.

Create with the following test cases:

Run the test with python test. All the tests should pass.

Let’s create the authentication endpoints for login and logout.

  • First we need a dto for the login payload. We will use the auth dto for the @expect annotation in login endpoint. Add the code below to the

  • Next, we create an authentication helper class for handling all authentication related operations. This will be in the service package and will contain two static methods which are login_user and logout_user

When a user is logged out, the user’s token is blacklisted ie the user can’t log in again with that same token.

  • Let us now create endpoints for login and logout operations.
    In the controller package, create with the following contents:

  • At this point the only thing left is to register the auth api namespace with the application Blueprint

Update file of app package with the following

# app/
from flask_restplus import Api
from flask import Blueprint

from .main.controller.user_controller import api as user_ns
from .main.controller.auth_controller import api as auth_ns

blueprint = Blueprint('api', __name__)

api = Api(blueprint,
description='a boilerplate for flask restplus web service'

api.add_namespace(user_ns, path='/user')

Run the application with python run and open the url in your browser.

The swagger documentation should now reflect the newly created auth namespace with the login and logout endpoints.

Before we write some tests to ensure our authentication is working as expected, let’s modify our registration endpoint to automatically login a user once the registration is successful.

Add the method generate_token below to

The generate_token method generates an authentication token by encoding the user id. This token is the returned as a response.

Next, replace the return block in save_new_user method below

response_object = {
'status': 'success',
'message': 'Successfully registered.'
return response_object, 201


return generate_token(new_user)

Now its time to test the login and logout functionalities. Create a new test file in the test package with the following content

Visit the github repo for a more exhaustive test cases.

Route protection and Authorization

So far, we have successfully created our endpoints, implemented login and logout functionalities but our endpoints remains unprotected.

We need a way to define rules that determines which of our endpoint is open or requires authentication or even an admin privilege.

We can achieve this by creating custom decorators for our endpoints.

Before we can protect or authorize any of our endpoints, we need to know the currently logged in user. We can do this by pulling the Authorization token from the header of the current request by using the flask library request.We then decode the user details from the Authorization token.

In the Auth class of file, add the following static method

Now that we can retrieve the logged in user from the request, let’s go ahead and create the decorators.

Create a file in the util package with the following content

For more information about decorators and how to create them, take a look at this link.

Now that we have created the decorators token_required and admin_token_required for valid token and for an admin token respectively, all that is left is to annotate the endpoints which we wish to protect with the freecodecamp orgappropriate decorator.

Extra tips

Currently to perform some tasks in our application, we are required to run different commands for starting the app, running tests, installing dependencies etc. We can automate those processes by arranging all the commands in one file using Makefile.

On the root directory of the application, create a Makefile with no file extension. The file should contain the following:

.PHONY: clean system-packages python-packages install tests run all

find . -type f -name '*.pyc' -delete
find . -type f -name '*.log' -delete

sudo apt install python-pip -y

pip install -r requirements.txt

install: system-packages python-packages

python test

python run

all: clean install tests run

Here are the options of the make file.

  1. make install : installs both system-packages and python-packages
  2. make clean : cleans up the app
  3. make tests : runs the all the tests
  4. make run : starts the application
  5. make all : performs clean-up,installation , run tests , and starts the app.

Extending the App & Conclusion

It’s pretty easy to copy the current application structure and extend it to add more functionalities/endpoints to the App. Just view any of the previous routes that have been implemented.

Feel free to leave a comment have you any question, observations or recommendations. Also, if this post was helpful to you, click on the clap icon so others will see this here and benefit as well.

Visit the github repository for the complete project.

Thanks for reading and good luck!

Structuring a Flask-RESTPlus Web Service for Production Builds was originally published in freeCodeCamp on Medium, where people are continuing the conversation by highlighting and responding to this story.



What's Your Reaction?

Cute Cute
Lol Lol
Love Love
Dislike Dislike
Fail Fail
Happy Happy
Confused Confused
Dam Dam
Angry Angry

Structuring a Flask-RESTPlus Web Service for Production Builds

log in

Don't have an account?
sign up

reset password

Back to
log in

sign up

Back to
log in
Choose A Format
Personality quiz
Series of questions that intends to reveal something about the personality
Trivia quiz
Series of questions with right and wrong answers that intends to check knowledge
Voting to make decisions or determine opinions
Formatted Text with Embeds and Visuals
The Classic Internet Listicles
Open List
Open List
Ranked List
Ranked List
Upload your own images to make custom memes
Youtube, Vimeo or Vine Embeds
Soundcloud or Mixcloud Embeds
Photo or GIF
GIF format