bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Staff Developer Advocate

Juan Cruz Martinez

Let's learn how to develop RESTful APIs with Python and Flask.

Developing RESTful APIs with Python and Flask

Ryan Quinn

Community Support and Engagement Specialist (FGA)

In this post, we will focus on adding fine-grained authorization to your Python Flask application using OpenFGA.

Fine-grained authorization (FGA) refers to the capability of granting individual users permission to perform particular actions on specific resources. Effective FGA systems enable the management of permissions for a large number of objects and users. These permissions can undergo frequent changes as the system dynamically adds objects and adjusts access permissions for its users.

[OpenFGA](https://openfga.dev/) is an open-source Relationship-Based Access Control (ReBAC) system designed by Okta for developers and adopted by the Cloud Native Computing Foundation (CNCF). It offers scalability and flexibility and supports the implementation of RBAC and ABAC authorization models. By moving authorization logic outside the application code, OpenFGA makes it simpler to evolve authorization policies as complexity grows.

[Flask](https://flask.palletsprojects.com/en/3.0.x/) provides a simple framework for rapidly creating web applications in Python. Using add-ons like [SQLAlchemy](https://www.sqlalchemy.org/) and authentication with Auth0, you can save development time and focus your efforts on your application’s core functionality.

In this guide, we will build a simple application that shows how to incorporate OpenFGA, allowing you to leverage the benefits of fine-grained authorization with Flask.

## Prerequisites

Before we start, let's be sure you have the following installed on your development machine:

- **Python 3.x**
- **Flask**
- **SQLAlchemy**
- **authlib**
- **requests**
- **[OpenFGA SDK for Python](https://github.com/openfga/python-sdk)**

Once you have Python installed, you can install the necessary packages using `pip3`.

> On some systems, the command `pip` may be used in place of `pip3`:

```bash
pip3 install Flask Flask-SQLAlchemy python-dotenv requests openfga_sdk authlib
```

You’ll also need an OpenFGA server instance running. You can use a managed instance like [OktaFGA](https://www.okta.com/products/fine-grained-authorization/) or set up a local instance with Docker with:

```bash
docker run -p 8080:8080 openfga/openfga run
```

## Project Setup

Let's set up the project structure:

```
flask_openfga_tutorial/
├── app/
│   ├── __init__.py
│   ├── models.py
│   ├── routes.py
│   ├── templates/
│   │   ├── base.html
│   │   ├── index.html
│   │   ├── resource.html
├── config.py
├── model.fga
├── run.py
└── requirements.txt
```

- `app/`: This directory contains our Flask application code, including our database model, our route handlers, and our functions that interact with OpenFGA.
- `templates/`: Contains HTML (jinja2) templates for our web interface.
- `config.py`: Configuration settings for Flask and OpenFGA.
- `model.fga`: Our OpenFGA authorization model.
- `run.py`: The entry point for our Flask application.
- `requirements.txt`: Lists our project dependencies.

## Configuring Flask, SQLAlchemy, and AuthLib

### config.py

In our `config.py`, we will define the configuration for our Flask application. We will read sensitive values using `os.getenv()`, which allows us to use a `.env` file in our project directory or from environment variables.

```python
# config.py

import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    SECRET_KEY = os.getenv('SECRET_KEY')
    SQLALCHEMY_DATABASE_URI = os.getenv('DATABASE_URL', 'sqlite:///db.sqlite3')
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    FGA_API_URL = os.getenv('FGA_API_URL', 'http://localhost:8080')
    FGA_STORE_ID = os.getenv('FGA_STORE_ID')
    FGA_MODEL_ID = os.getenv('FGA_MODEL_ID')
    AUTH0_CLIENT_ID = os.getenv('AUTH0_CLIENT_ID')
    AUTH0_CLIENT_SECRET = os.getenv('AUTH0_CLIENT_SECRET')
    AUTH0_DOMAIN = os.getenv('AUTH0_DOMAIN')
```

### app/__init__.py

Next, we will initialize Flask, SQLAlchemy, OAuth, and our OpenFGA Client in `app/__init__.py`:

```python
# app/__init__.py

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from authlib.integrations.flask_client import OAuth
from openfga_sdk.client import ClientConfiguration
from openfga_sdk.sync import OpenFgaClient
from config import Config
import os


db = SQLAlchemy()
oauth = OAuth()

def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)

    db.init_app(app)
    oauth.init_app(app)

    # Configure and initialize the Auth0 Client
    oauth.register(
        "auth0",
        client_id=app.config["AUTH0_CLIENT_ID"],
        client_secret=app.config["AUTH0_CLIENT_SECRET"],
        client_kwargs={
            "scope":"openid profile email",
        },
        server_metadata_url=f'https://{app.config["AUTH0_DOMAIN"]}/.well-known/openid-configuration'
    )
    
    #Configure and initialize the OpenFGA Client
    configuration = ClientConfiguration(
        api_url=app.config['FGA_API_URL'],
        store_id=app.config['FGA_STORE_ID'],
        authorization_model_id=app.config['FGA_MODEL_ID'],
    )

    app.fga_client = OpenFgaClient(configuration)
    app.fga_client.read_authorization_models()

    from .routes import main as main_blueprint
    app.register_blueprint(main_blueprint)

    with app.app_context():
        db.create_all()

    return app

```

## Creating Our Launch Script

### run.py

Our `run.py`, in the root directory of our project, is the script we will call in order to run our Flask application:

```python
# run.py

from app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

```

## Defining the Database Models

### app/models.py

We will define the `Resource` model in `app/models.py` to keep track of the resources users create.

```python
# app/models.py

from . import db
import uuid

class Resource(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    uuid = db.Column(db.String(36), unique=True, nullable=False, default=lambda: str(uuid.uuid4()))
    name = db.Column(db.String(120), nullable=False)
    owner = db.Column(db.String(255), nullable=False)

```

## Setting Up the OpenFGA Model

Next, we will create our authorization model in the file `model.fga`. This model will define the types of relationships that can exist between our users and objects:

```plaintext
model
  schema 1.1

type user
  relations
    define owner: [user]

type resource
  relations
    define owner: [user]
    define viewer: owner

```

This model defines two types, `user` and `resource`, and establishes an `owner` relationship. The `viewer` relation is defined to be the same as the `owner`, meaning only owners can view the resource.

### Writing the Model to OpenFGA

We will use the OpenFGA CLI to write our new model for our OpenFGA store. Check the OpenFGA docs to learn [how to use the CLI to create a store](https://openfga.dev/docs/getting-started/cli) where you can write your model. Remember, models, are immutable, so anytime you make changes; you need to write the updated model and update the model ID used in your application.

First, we will create a store where we'll write our model:

```
fga store create --name "FGA Flask Demo Store"
```

The result of that command will include our `store id`, which we will use in our next command to write the model.

```bash
fga model write --store-id <store_id> --file model.fga
```
## Configuring Authentication
This app uses Auth0 for authentication, so to get started, we will need to configure our application to enable authentication.

### Create an Auth0 Account
If you do not have an Auth0 account, create one [here for free](https://auth0.com/signup). 

### Configure an application
Use the interactive selector to create a new Auth0 application.

- Application Type
For Application Type, select "Single Page Application."

- Allowed Callback URLs
Enter `http://localhost:3000/callback` in "Allowed Callback URLs"

- Allowed Logout URLs
Enter `http://localhost:3000/` in "Allowed Logout URLs"

- Allowed Web Origins
Enter `http://localhost:3000` in "Allowed Web Origins"

By default, your app will have two "Connections" enabled to provide user authentication data.

- google-oauth2 - This option allows users to log in with Google. There is no need to configure user accounts with this option
- Username-Password-Authentication - This option allows you to create user accounts in the Auth0 dashboard by specifying usernames and passwords

### Collect required credentials
From your application's page in the Auth0 Dashboard, copy your app's `Domain`, `Client ID`, and `Client Secret`, which we will use later when we configure our application.

## Implementing Routes with AUTH0 and Openfga

### app/routes.py

Next, create the application routes in `app/routes.py`:

```python
# app/routes.py

from flask import Blueprint, request, render_template, redirect, url_for, flash, session, current_app
from .models import Resource, db
from urllib.parse import quote_plus, urlencode
from openfga_sdk.client.models import ClientTuple, ClientWriteRequest, ClientCheckRequest
from app import oauth
import uuid
from functools import wraps

main = Blueprint('main', __name__)

def login_required(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        # This decorated function can be applied to route handers and will ensure that a valid user session is active.
        # If the requestor is not logged in it will redirect their browser to the home page
        if 'user_info' not in session:
            return redirect(url_for('main.login'))
        return f(*args, **kwargs)
    return decorated_function

@main.route("/login")
def login():
    # Login function redirects to the Auth0 login page for our app
    return oauth.auth0.authorize_redirect(
        redirect_uri=url_for("main.callback", _external=True)
    )

@main.route("/callback", methods=["GET", "POST"])
def callback():
    # The callback function that Auth0 will redirect users to after authentication
    try:
        token = oauth.auth0.authorize_access_token()
        session["user_info"] = token['userinfo']    
        session['user_email'] = token['userinfo']['email']
    except Exception as e:
        return redirect(url_for("main.index"))
    return redirect(url_for("main.index"))
    
    

@main.route("/logout")
def logout():
    # Log a user out of the app, clear the session and redirect them to the Auth0 logout url for our app
    session.clear()
    return redirect(
        "https://" + current_app.config["AUTH0_DOMAIN"]
        + "/v2/logout?"
        + urlencode(
            {
                "returnTo": url_for("main.index", _external=True),
                "client_id": current_app.config["AUTH0_CLIENT_ID"],
            },
            quote_via=quote_plus,
        )
    )

@main.route('/')
@login_required
def index():
    resources = Resource.query.all()
    return render_template('index.html', resources=resources, user_info=session.get['user_info'])

@main.route('/create_resource', methods=['POST'])
@login_required
def create_resource():
    resource_name = request.form.get('name')

    resource = Resource(name=resource_name, owner=session.get['user_email'])
    db.session.add(resource)
    db.session.commit()

    # Create a tuple in OpenFGA
    fga_client = current_app.fga_client
    write_request = ClientWriteRequest(
        writes=[
            ClientTuple(
                user=f"user:{session.get['user_email']}",
                relation="owner",
                object=f"resource:{resource.uuid}",
            ),
        ],
    )
    fga_client.write(write_request)

    return redirect(url_for('main.resource', resource_uuid=resource.uuid))

@main.route('/resource/<resource_uuid>')
@login_required
def resource(resource_uuid):
    resource = Resource.query.filter_by(uuid=resource_uuid).first()
    if not resource:
        flash('Resource not found.')
        return redirect(url_for('main.index'))

    # Check permission using OpenFGA
    fga_client = current_app.fga_client
    check_request = ClientCheckRequest(
        user=f"user:{session.get['user_email']}",
        relation="viewer",
        object=f"resource:{resource.uuid}",
    )
    response = fga_client.check(check_request)

    if not response.allowed:
        flash('You do not have permission to view this resource.')
        return redirect(url_for('main.index'))

    return render_template('resource.html', resource=resource)
```

- **User Login**: Users can register or log in using Auth0 via the `login` route.
- **Resource Creation**: Users can create resources, and ownership is established by writing a tuple to OpenFGA.
- **Resource Viewing**: Access to resources is controlled by checking permissions with OpenFGA.

## Creating our Web Templates

### Base Template: `templates/base.html`

Create a base template for consistent layout, our other templates will inherit their top level layout from this template.

```html


<!doctype html>
<html lang="en">
<head>
    <title>{% block title %}OpenFGA Tutorial{% endblock %}</title>
</head>
<body>
    {% with messages = get_flashed_messages() %}
      {% if messages %}
        <ul>
        {% for message in messages %}
          <li>{{ message }}</li>
        {% endfor %}
        </ul>
      {% endif %}
    {% endwith %}
    {% block content %}{% endblock %}
    <a href="/logout">Log Out</a>
</body>
</html>
```

### Index template: `templates/index.html`

This page extends our base template and provides the UI elements for the main page of our application.

```html


{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h2>Welcome, {{ user_info.name }}!</h2>

<h3>Create a Resource</h3>
<form method="POST" action="{{ url_for('main.create_resource') }}">
    <input type="text" name="name" placeholder="Resource Name" required>
    <button type="submit">Create</button>
</form>

<h3>Resources</h3>
<ul>
    {% for resource in resources %}
        <li><a href="{{ url_for('main.resource', resource_uuid=resource.uuid) }}">{{ resource.name }}</a></li>
    {% else %}
        <li>No resources available.</li>
    {% endfor %}
</ul>
{% endblock %}
```

### Resource template: `templates/resource.html`

This page extends our base template and displays a list of resources a user has access to.

```html


{% extends "base.html" %}
{% block title %}Resource Details{% endblock %}
{% block content %}
<h2>Resource: {{ resource.name }}</h2>
<p>Owned by: {{ resource.owner }}</p>
<a href="{{ url_for('main.index') }}">Back to Home</a>
{% endblock %}
```

## Testing the Application

### Configuration variables

Our application expects several variables to be set as environment variables or in a .env file in our project directory. For this example, we will create a .env file with the following content, including the model and store we created earlier and our Auth0 application details:

```plaintext
SECRET_KEY="your_secret_key"
DATABASE_URL="sqlite:///db.sqlite3"
FGA_API_URL="http://localhost:8080"
AUTH0_CLIENT_ID=""
AUTH0_CLIENT_SECRET=""
AUTH0_DOMAIN=""
FGA_STORE_ID="your fga store id"
FGA_MODEL_ID="your fga model id"
```

- `SECRET_KEY`: A unique value used internally to secure session data in Flask.
- `DATABSE_URL`: In our example, we are using SQLite, but you can also use a MySQL or PostgreSQL connection string.
- `FGA_API_URL`: The URL to connect to your OpenFGA instance. The example above assumes you are running OpenFGA in Docker locally using the command provided earlier.
- `AUTH0_CLIENT_ID`:  The client ID from our application page in the Auth0 Dashboard.
- `AUTH0_CLIENT_SECRET`: The client secret from our application page in the Auth0 Dashboard.
- `AUTH0_DOMAIN`: The domain from our application page in the Auth0 Dashboard.
- `FGA_STORE_ID`: This is the store ID that was returned when you created a store in your OpenFGA instance.
- `FGA_MODEL_ID`:  This is the model ID that was returned when you ran `fga write` to write your model.

### Run the Flask App

Start the application:

```bash
python run.py
```

### Get Started

- Open your browser and navigate to `http://127.0.0.1:5000/`.
- You will be redirected via our login route handler to log in via Auth0. You can log in via one of the OAuth providers you selected or with user accounts created in the Auth0 Dashboard.

### Create a Resource

- After logging in, create a resource by entering a name and clicking "Create".
- The resource will be added to the database, and an ownership tuple will be written to OpenFGA.

### View the Resource

- Click on the resource name to view its details.
- OpenFGA checks whether you have permission to view the resource based on the `viewer` relation.

### Test Access Control

- Log out and create a new user either by logging in with a different OAuth account or by adding another set of login credentials in the Auth0 dashboard.
- Try to access the resource created by the first user by entering its URL directly.
- You should receive a message stating you do not have permission to view the resource.

## Next Steps

This guide presented a basic example of how OpenFGA can be used within a Python Flask application to manage authorization and access to resources. You can find a more detailed example application that implements a web application allowing users to share text files and folders and covers topics including parent-child relationships and sharing resources with others [in this project](https://github.com/openfga/flask-demo).

OpenFGA for Python Flask Applications

Learn how to design and build REST APIs with Python and Flask following best practices.

Python is my favorite programming language. Its adaptability, readability, and coding speed are unique and make [python a powerful choice in various projects](https://livecodestream.dev/post/what-is-python-best-for/), from data science projects to scripting and, of course, APIs.

Python is a popular choice for API development, not only because it is one of the [most loved programming languages](https://insights.stackoverflow.com/survey/2020#technology-most-loved-dreaded-and-wanted-languages), but also because of its rich ecosystem of libraries and frameworks that serve that goal, libraries with immense popularity such as [Django](https://www.djangoproject.com/), [Flask](https://flask.palletsprojects.com/), and [FastAPI](https://fastapi.tiangolo.com/).

But which framework should you use to build your APIs with Python? It’s 100% up to you, but there are important considerations to keep in mind. After all, some of these frameworks are different, even from the ideology.

- Django is an all-inclusive framework. It provides tools and modules for handling API requests, serialization, database connections, automatic admin UI generation, and so much more.
- Flask, on the contrary, is a minimalist framework, it provides only the necessary tools, but it extends its functionality with additional libraries and frameworks. The great part is, you decide exactly what you need for your project, nothing more.
- FastAPI is a relatively new framework. It makes use of newer python features such as type-hints, concurrency handling (with async), and it’s super fast.

I work a lot with Flask and FastAPI, and I love both. I love the flexibility and adaptability of these frameworks, and for today's article, we will be focusing on Flask.

The following tips and practices are the result of research and more than eight years of experience building and shipping production-grade APIs with Python:

- Design your API endpoints with proper names and HTTP verbs
- How to properly structure your application
- Build your documentation from the code
- Testing

<br>
**Let’s get started!** 🚀

## Design Your API Endpoints with Proper Names and HTTP Verbs

An adequately designed API is easy and straightforward for developers to understand. By reading the [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) and HTTP verb (more on this later), a developer can pretty much have a good understanding of what to expect to happen when calling a particular method.

But how does that work? Let’s start with naming URIs. In REST, we called `Resource` to a first-level data representation. Naming these resources **consistently** throughout your API will turn out to be one of the best decisions for the long term.

Note that I highlighted consistently in the previous sentence, as it’s a key factor. Sure, there are particular ways to name your resources, and we will cover them, but being consistent is more important to the actual convention you choose.

Let’s start getting practical by modeling a simple eCommerce website with customers, orders, and a checkout process.

Our primary resource is `customers`, which is a collection of the instance `customer`. With this information, we can identify the collection resource by the URI `/customers` or a single resource by using the URI `/customers/{customerId}`. Subsequently, we can identify sub-resources such as `orders`, and we can identify them as `/customers/{customerId}/orders`, or a single order resource by `/customers/{customerId}/orders/{orderId}`.

### Best practices naming resources

1. Use nouns in their plural form to represent resources, eg:
    - ✅ Users of a system: `/users`, `/users/{userId}`
    - ✅ User’s playlists: `/users/{userId}/playlists`, `/users/{userId}/playlists/{playlistId}`
2. Use hyphens “-” to separate words and improve redeability
    - ✅ `/users/{userId}/-mobile-devices`
    - ❌ `/users/{userId}/mobileDevices`
    - ❌ `/users/{userId}/mobile_devices`
3. Use forward slashes “/’ to indicate hierarchy
    - ✅ `/users/{userId}/mobile-devices`
    - ❌ `/users-mobile-devices/{userId}`
    - ❌ `/users-mobile-devices/?userId={userId}`
4. Use only lowercase letters in URIs
    - ✅ `/users/{userId}/mobile-devices`
    - ❌ `/Users/{userId}/Mobile-Devices`

Now that we understand how to name resources, we need to think about actions. There are methods in our APIs that are procedural by nature and are not related to a specific resource, e.g., checkout, run, play, etc.

### Best practices naming actions

1. Use verbs to represent actions, e.g.:
    - ✅ Execute a checkout action: `/users/{userId}/cart/checkout`
2. Same as resources, use hyphens, forward slashes, and lowercase letters.

One crucial point here is to differentiate between CRUD functions and actions, as both are actions. In REST, CRUD operations, such as Create, Read, Update and Delete, are handled through HTTP verbs and not by the URI.

### But what are HTTP verbs or HTTP request methods?

HTTP defines a set of request methods to indicate an action to be performed for a resource (sounds familiar?). The list includes several, but we will be focusing on 5:

- **GET**: should be for data retrieval.
- **POST**: should be used to create a new resource.
- **PUT**: should be used to update information about a specific resource.
- **DELETE**: should be used to delete a particular resource.
- **PATCH**: should be used to update partial information about a particular resource.

### Example for our eCommerce website

- ✅ **GET** `/users`: lists of all users.
- ✅ **POST** `/users`: creates a new user.
- ✅ **PUT** `/users/{userId}`: updates a user.
- ✅ **DELETE** `/users/{userId}`: deletes a specific user.
- ✅ **PATCH** `/users/{userId}`: partially updates a user.
- ✅ **GET** `/users/{userId}/orders`: lists of all orders for a particular user.
- ✅ **POST** `/users/{userId}/cart/checkout`: runs the checkout process.

What you shouldn't do:

- ❌ `/users/get-all`
- ❌ `/users/create`
- ❌ `/users/{userId}/list-orders`

In any form of GET, POST, or another verb.

## How to Properly Structure Your Application

I’d like to start this section by saying that there’s no one correct way to structure your application depending on application size, modules, requirements, or even personal preferences. This could vary. However, I’d like to introduce you to how my team structures Flask applications, and we used this setup for multiple production projects.

You can follow the explanation of the structure in the article, and you can also find this structure ready to use in the [Flask API starter kit on github](https://github.com/bajcmartinez/flask-api-starter-kit).

```text 
project/
    api/
        model/
            __init__.py
            welcome.py
        route/
            home.py
        schema/
            __init__.py
            welcome.py
        service
            __init__.py
            welcome.py

    test/
        route/
            __init__.py
            test_home.py
        __init.py

    .gitignore
    app.py
    Pipfile
    Pipfile.lock
```

Let’s now break it down and explain each module.

All the application magic happens inside the API module (`/api`), there, we split the code into 4 main parts:

- The `models` are the data descriptor of our application, in many cases related to the database model. How each model is defined will heavily depend on the library you use to connect to your database.
- The `routes` are the URIs to our application, where we define our resources and actions.
- The `schemas` are the definitions for inputs and outputs of our API, what parameters are allowed, what information we will output. They correlate to our resources, but they are not necessarily the same as our models.
- The `services` are modules that define application logic or interact with other services or the db layer. Routes should be as simple as possible and delegate all logic to the services.    

Each endpoint in Flask can be defined on its own or by groups called [blueprints](https://flask.palletsprojects.com/en/2.0.x/blueprints/). In my case, I like the grouping Blueprints provide, and I use them for each resource. Let’s take a look at what an example of our welcome route (`./api/route/home.py`) would look like:

```python
from http import HTTPStatus
from flask import Blueprint
from flasgger import swag_from
from api.model.welcome import WelcomeModel
from api.schema.welcome import WelcomeSchema

home_api = Blueprint('api', __name__)


@home_api.route('/')
@swag_from({
    'responses': {
        HTTPStatus.OK.value: {
            'description': 'Welcome to the Flask Starter Kit',
            'schema': WelcomeSchema
        }
    }
})
def welcome():
    """
    1 liner about the route
    A more detailed description of the endpoint
    ---
    """
    result = WelcomeModel()
    return WelcomeSchema().dump(result), 200
```

Let’s break all of it into 3 pieces:

```python
home_api = Blueprint('api', __name__)
```

Here is where we declared our Blueprint, which we can consequently use to declare our endpoints or routes. In this case, our grouping is pretty basic, but we can do much more with grouping, like defining prefixes, resource folders, and more.

For example if we would like to have our `home` blueprint always as a nested route of `/home-service`, we could do:

```python
home_api = Blueprint('api', __name__, url_prefix='/home-service')
```

Next we declare one route, but we split it in 2 parts:

```python
@home_api.route('/')
@swag_from({
    'responses': {
        HTTPStatus.OK.value: {
            'description': 'Welcome to the Flask Starter Kit',
            'schema': WelcomeSchema
        }
    }
})
```

We use annotations on top of functions to convert them into endpoints and provide additional information, e.g., documentation information, more on that in the next section.

And finally, our route code, which is just a Python function.

```python
def welcome():
    """
    1 liner about the route
    A more detailed description of the endpoint
    ---
    """
    result = WelcomeModel()
    return WelcomeSchema().dump(result), 200
```

Note that we don’t simply return a string or JSON object directly, but we use our schemas instead. In our example, I’m using [flask-marshmallow](https://flask-marshmallow.readthedocs.io/en/latest/) serialization library for its purposes.

## Build Your Documentation from the Code

You build your API, you shipped to production, and developers are eager to consume it, but how would they know what endpoints are available and how to use them? The simple answer is by reading the documentation.

The documentation can be built in 2 ways, you can open up an editor and write it “manually”, or you can use the code to generate your documentation. If you like the idea of automatic documentation, you will love [swagger](https://swagger.io/).

Swagger is an open-source specification that allows you to describe each element of your API so that any machine or system can interpret it and interact with it. Thanks to this specification, many tools have been developed to provide rich interfaces to make our documentation dynamic and interactive, but also to provide developers with tools to easily generate these swagger files.

For Flask, there are multiple libraries for automatic Swagger generation, but my favorite is [flasgger](https://github.com/flasgger/flasgger). Flassger provides annotations and other tools to generate your documentation, and it also provides a pretty web interface where you can see each endpoint, its inputs, and outputs and even run the endpoints directly from the docs.

Here is an image of it in action:

![Swagger demo page](https://images.ctfassets.net/23aumh6u8s0i/3Dz9nOtHkd2JlQxbcCKKKQ/b65d997f2bf20418a7143279e096940b/swagger_demo.png)

It’s highly configurable and compatible with our serialization library by using an additional library called [apispec](https://apispec.readthedocs.io/en/latest/). It’s all pretty easy to set up, but you can also make use of the [Flask starter kit](https://github.com/bajcmartinez/flask-api-starter-kit), and you will have it all done for you.

But once you have it up and running, where is the information taken for the docs? From 2 places:

- Remember our swag_from function annotation? There we can provide detailed information about the inputs and outputs

    ```python
    @swag_from({
        'responses': {
            HTTPStatus.OK.value: {
                'description': 'Welcome to the Flask Starter Kit',
                'schema': WelcomeSchema
            }
        }
    })
    ```

- We can also use string literals in functions to provide a description for the endpoint, similar to what we did here:

    ```python
    def welcome():
        """
        1 liner about the route
        A more detailed description of the endpoint
        ---
        """
    ```

There are many more options and customizations; it’s all well documented on their [official docs](https://github.com/flasgger/flasgger).

## Testing

If you are like me, perhaps you hate writing tests, but if you are like me, you know it’s worth it. Testing, when done properly, increases efficiency and quality in the long run. They also reassure developers when making changes, refactoring, or building new features on existing systems.

Building tests shouldn’t be too hard, and it should happen naturally during development. I struggled a lot with it in the past because I’d always first develop the feature, the endpoint, or the function and then write the tests, just to get it done.

I’m not saying that approach is wrong, but there’s a better way. TDD, or test-driven development, it’s a concept idea where you write tests first, and just then you write the actual code we want to test.

How does it work? Let’s suppose we need to write a function that will add 2 numbers and return the result; exciting, right?

With TDD, our approach would be first to write the tests.

```python
def test_answer():
    assert sum_two_numbers(3, 5) == 8
```

Next, we run the tests, and it fails because our function doesn’t even exist yet. So next, we write our function:

```python
def sum_two_numbers(num1, num2):
    return num1 * num2
```

Next, we rerun our tests, and they still fail. Our assertion fails, but why? It turns out that I made a simple mistake. As clumsy as I am, I put a * instead of a +; this would have been very hard to notice without our tests, but thanks god, we have them.

We fix our function, and now everything runs perfectly.

```python
def sum_two_numbers(num1, num2):
    return num1 + num2
```

In the exercise we did, it sounds kind of silly, but with more complex functions and code mistakes happen, and having tests first will help a lot; I say that from experience.

## Conclusion

Best practices can be different for different frameworks, problems to solve, or even people, there’s no one way of doing things right, and that’s something I love about programming. However, having basic principles to rely on when designing and developing APIs can help your team, and other developers consume your API products.

Being consistent in naming, separating concepts in modules or folders in your project, documenting directly from your code, and properly testing are just examples of things that can make your life easier, more productive, and take you to the next level.

I hope you enjoyed reading this article!

Best Practices for Flask API Development

jess-author

Jessica Temporal is a Senior Developer Advocate at Auth0 and co-founder of the first Brazilian data science podcast called <a target='_blank' href='https://pizzadedados.com'><strong>Pizza de Dados</strong></a>. She’s the author of <a target='_blank' href='https://www.amazon.com/dp/B0CDNX6NS7/ref=sr_1_1?&_encoding=UTF8&tag=jesstempora0e-20&linkCode=ur2&linkId=efc4229f6b816609dfce4f185781d99a&camp=1789&creative=9325' ><strong>The Big Git Microbook</strong></a>, creator of <a target='_blank' href='https://gitfichas.com/en'><strong>GitFichas.com</strong></a>, and a part of <a target='_blank' href='https://www.linkedin.com/learning/instructors/jessica-temporal'><strong>LinkedIn Learning</strong></a> instructors team. Jessica helped develop the AI that identifies possible unlawful expenses from Brazilian politicians. She is part of the PyLadies initiative that works to improve diversity and inclusion in technology. In her free time, she likes to knit, play video games, use her 3D printer, and is learning to create 3D models.

Sr. Developer Advocate

Jessica Temporal

Flask 2.0.0 was released a while ago and many interesting changes are available

Flask is the most used framework for web development according to the Jetbrains [Python Developers Survey from 2020](https://www.jetbrains.com/lp/python-developers-survey-2020/), and in May of 2021, version `2.0.0` of Flask came out with 31 new changes.
In this post, you'll learn about some of those changes and the refactoring you might want to do to your code to take the most advantage of this new version.

## What's New?

At the beginning of this post, I mentioned 31 alterations were added to this release of the framework, and [you can read about all of them here](https://flask.palletsprojects.com/en/2.0.x/changes/#version-2-0-0). 

First and foremost, the most critical change on Flask `2.0.0` is that Flask **officially dropped support for Python 2 and 3.5**. If you are using these versions on your projects **and want** to update to Flask `2.0.0`, you need to also update the Python version you are using.

<include src="TweetQuote" quoteText="Flask officially drops support for Python 2 and 3.5! Time to update the Python version in your projects!"/>

But let focus on the 3 things that I personally like the most:

- Type hinting is here!
- You can read the application configuration from any file.
- My favorite syntactic sugar just arrived: HTTP method-specific decorators for defining routes.

## How To Upgrade

Let's start at the beginning: Upgrading Flask's version. For running an app locally, just remember to activate your Python environment (if you use one) and run the following:

```console
pip install -U Flask==2.0.0
```

The `-U` flag tells `pip` to upgrade the version of Flask on your environment to version `2.0.0`. After that, it is time to update the codebase. If your codebase uses unit or integration tests, it is a great time to see if any of them break and to fix the code accordingly. 😉

After doing the upgrade, you might want to also update your environment files like `requirements.txt` and `Pipenv`.

## Type Hinting

As [**The Zen of Python**](https://www.python.org/dev/peps/pep-0020/) states: _Explicit is better than implicit_, and type hinting is a beautiful way of _explicitly_ telling anyone reading a class or function documentation what that object expects as a parameter. Now, all of Flask has typing annotations.

Consider this: it has been a while since you used Flask, and you don't quite remember what a given parameter receives. You might not even remember what type of object that parameter receives. You might try to find the examples for the class you want to use, or now you can simply check the class signature by using the help function, and it will clearly state what that parameter receives.

Let's see a more concrete example. Let's check out the help for the Flask class, but let's see how it was before first.

Here I have an environment with Flask on version `1.1.4` (the last version before `2.0.0`), and when I open up the `python` console and import the `Flask` class and then call the `help()` function to display the class documentation:

```python
from flask import Flask
help(Flask)
```
This is what you'll see:

![Screenshot of the help documentation for Flask class object before upgrading Flask](https://images.ctfassets.net/23aumh6u8s0i/cLF8UiM4DsY8sQn1onxLX/e63b3a86fe5f041eec0f3ce9cbab6cd8/01_help_flask_class_terminal_before.png)

Now, if you do the same thing in a Python environment with Flask `2.0.0`, this is what you'll see:

![Screenshot of the help documentation for Flask class object after upgrading Flask](https://images.ctfassets.net/23aumh6u8s0i/7MAf0w2mgarPNHoHz46I4D/a749d1a9ba34c6c0bdc0811e93fe8e04/02_help_flask_class_terminal_after.png)

If you look closely, you can see that `instance_relative_config` should receive a boolean value instead of assuming it would be _boolean_ because the default for that parameter is `False`.

This isn't a change that prompts you to update your code, but it will come in handy when you start writing new endpoints or adding more functionality to the ones already there.

## Reading The Configuration From Any File

Depending on size, objective, or even personal taste, you might like to load the configurations for your application from a file.

So you might already read your configuration from a JSON file, but guess what?! Now you can read the configuration from _any_ type of file as long as a file reader can understand those files. So if you were longing to have TOML files holding your configuration information, rejoice! Now you can! 🎉

Let's take a closer look and see how that works. Let's say you have the following TOML to hold your configuration and that you already have the [`toml` package](https://pypi.org/project/toml/) installed on your environment:

```bash
# config.toml

DEBUG = true
SECRET_KEY = "development key"
```

Now all you have to do is use the new `.from_file()` method to read the variables from the configuration file. This is done by passing the file path and the file reader to the `.from_file()` method:

```python
import toml

from flask import Flask


app = Flask('__name__')
app.config.from_file('config.toml', toml.load)
```

Also, if you were using the `.from_json()` to load your configs, that has been deprecated! You'll need to update your code to use the `.from_file()` method. You probably had something like this before:

```python
from flask import Flask


app = Flask('__name__')
app.config.from_json('config.json')
```

Here's the updated version using the `.from_file()` method:

```python
import json

from flask import Flask


app = Flask('__name__')
app.config.from_file('config.json', json.load)
```
The most important thing to keep in mind when using `.from_file()` is that you have to have a function that parses that type of file, which means you might need to import new modules or libraries for reading and parsing that file. In the example above, I used the `json` module to read the configuration from a JSON file, whereas to read from a TOML file, I had to install the `toml` package.

With those changes, you should be good to go. 😉

## New HTTP Method Specific Decorators

Finally, my favorite change: HTTP method-specific decorators! If you've been doing RESTful APIs using Flask, you are probably accustomed to doing something like the following code snippet:

```python
from flask import Flask


app = Flask('__name__')


@app.route('/first', methods=['GET'])
def my_get_endpoint():
    return 'This was a GET request.'


@app.route('/second', methods=['POST'])
def my_post_endpoint():
    return 'This was a POST request.'


@app.route('/third', methods=['PUT'])
def my_put_endpoint():
    return 'This was a PUT request.'
```

This Flask version provides syntactic sugar that allows you to register routes for the most common HTTP methods (`GET`, `POST`, `PUT`, `DELETE`, and `PATCH`) in a more direct way like other frameworks such as [FastAPI](http://fastapi.tiangolo.com) are doing. If you want to use this, you just have to change your traditional `@app.route` for a `@app.<method>`. Here is a refactored version of the above example:

```python
from flask import Flask


app = Flask('__name__')


@app.get('/first')
def my_get_endpoint():
    return 'This was a GET request.'


@app.post('/second')
def my_post_endpoint():
    return 'This was a POST request.'


@app.put('/third')
def my_put_endpoint():
    return 'This was a PUT request.'
```

This isn't a mandatory change. You can still use the traditional `@app.route` method to register your endpoints, but know that the syntactic sugar is available to you now.


## Wrapping Up

There were many changes made in this release of Flask, and I only covered a few of them in this blog post. What were your favorite changes, and why? Are you planning on upgrading to the newest version of Flask? Leave your comments and questions on the [community forum](http://community.auth0.com). 😉

Also, the code I showed here is available [in this repository on GitHub](https://github.com/auth0-blog/whats-new-flask-2).

What's new in Flask 2.0

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

Build a Flask and GraphQL quidditch management system that uses Auth0 rules to implement ABAC and GBAC.

Dynamic Authorization with GraphQL and Rules

In this series, you will learn how to create modern web applications with Python, Flask, and Angular.

Using Python, Flask, and Angular to Build Modern Web Apps - Part 3

Using Python, Flask, and Angular to Build Modern Web Apps - Part 2

Using Python, Flask, and Angular to Build Modern Web Apps - Part 1

Let's learn how to use SQLAlchemy ORM to persist and query data on Python applications.

"flask"