Part 3: API Configuration and User Registration

Project Structure

The chart below shows the folder structure for this section of the tutorial. In this post, we will work on all files marked as NEW CODE. Files that contain code from previous sections but will not be modified in this post are marked as NO CHANGES.

. (project root folder)
|- src
|   |- flask_api_tutorial
|       |- api
|       |   |- auth
|       |   |   |- __init__.py
|       |   |   |- business.py
|       |   |   |- dto.py
|       |   |   |- endpoints.py
|       |   |
|       |   |- widgets
|       |   |   |- __init__.py
|       |   |
|       |   |- __init__.py
|       |
|       |- models
|       |   |- __init__.py
|       |   |- user.py
|       |
|       |- util
|       |   |- __init__.py
|       |   |- datetime_util.py
|       |   |- result.py
|       |
|       |- __init__.py
|       |- config.py
|
|- tests
|   |- __init__.py
|   |- conftest.py
|   |- test_auth_register.py
|   |- test_config.py
|   |- test_user.py
|   |- util.py
|
|- .env
|- .gitignore
|- .pre-commit-config.yaml
|- pyproject.toml
|- pytest.ini
|- README.md
|- run.py
|- setup.py
|- tox.ini


KEY:
FOLDER
NEW CODE
NO CHANGES
EMPTY FILE

Introduction

It’s finally time to start configuring the API! Keep in mind that the URL routes and the business logic that takes place when a user sends a GET, POST, PUT or DELETE request could all be accomplished using the functions, classes and decorators provided in Flask (that is, without using the Flask-RESTx extension). However, doing so would require considerably more code and would not give us the Swagger UI page to document and test the API.

Before we begin, let’s discuss what makes a REST API RESTful and make a decision to abide (or not to abide) by the requirements and constraints of REST.

Understanding REST

The term “REST” was introduced in 2000 by Roy Fielding in his doctoral thesis, titled Architectural Styles and the Design of Network-based Software Architectures. I strongly recommend trying to fully digest Fielding’s thesis. At the very least you should read Chapter 5 Representational State Transfer (REST).

What makes an API RESTful is much more than creating a set of URIs and implementing the response to GET, POST, PUT, etc. requests. First of all, REST does not require HTTP – REST is protocol-agnostic. HTTP just happens to be very popular and well-suited to REST systems. REST is truly about resource state, and how hypermedia defines the actions available to these resources. REST is also about the media types that the system uses to represent the resources.

I say these things because most so-called REST APIs and articles explaining how to design and construct a REST API are not truly RESTful. In this section of the tutorial we will implement the user registration and authentication processes. What is the correct way to design a REST API to perform these actions? Are these actions even appropriate for a REST API? The answer is not as straightforward or obvious as you might think.

User Authentication in a RESTful System

The following questions/topics are from stackoverflow:

• Understanding REST: Verbs, error codes, and authentication
• RESTfully design /login or /register resources?
• Which HTTP method should Login and Logout Actions use in a “RESTful” setup
• How to design a restful url for login?
• Do sessions really violate RESTfulness?
• RESTful Authentication

I recommend skimming these discussions. What I took away from them is that there is nothing close to a consensus on the topic of the “correct” way to design a RESTful authentication system. The design that we will implement ensures that the client’s application state is never stored by the server, which adheres to the statelessness constraint of REST. However, the design I chose for the endpoint names clearly violates the naming requirements for RESTful URIs.

I believe that you should follow the tenets of REST as long as it makes sense for your application. For an authentication API, I believe the best design is to use routes with the verbs /register, /login, etc. A RESTful design where all routes strictly refer to a resource such as /session is far less intuitive, IMO.

Bearer Token Authentication

RFC6750 is the specification document that defines an authorization process where clients utilize tokens issued by a resource server to access protected resources. The tokens are exchanged via HTTP response fields and header fields. RFC6750 defines the required format and contents of these fields, as well as recommended best practices for mitigating possible security threats.

RFC6750 is a concrete implementation of the OAuth 2.0 Authorization Framework. OAuth 2.0 has its own specification document, RFC6749. To avoid duplicating work and to make maintenance of these reference docs easier, quite often terminology referred to in the Bearer Token Authentication spec references RFC6749 for the full definition/explanation. Because of this, I will refer to both documents and reproduce text whenever I am implementing something in order to fulfull a requirement for Bearer Token Authentication.

My intent is to adhere to the requirements in every possible case. Please let me know if you believe I have implemented anything incorrectly.

API Versioning

After you develop and release an API, it is important to remember that even minor changes such as a value in the request or response data changing from a string to an int could be a breaking change for clients. The best way to avoid causing frustration is to apply strict versioning with the promise that no breaking changes will be introduced within a major version.

There are several approaches to API versioning, but the one I prefer is the most explicit – embed the version number in the URL route. For example, the API route that registers a new user account will be /api/v1/auth/register. The /api/v1 prefix will apply to all API routes, and clients will expect that any tools or proceses that integrate with our API will continue to function as long as they use the same URI.

This post on the SparkNotes blog provides a nice summary of the types of changes that are breaking changes and the types that are not:

API Configuration with Flask-RESTx

Just like every other extension, Flask-RESTx can be initialized with a Flask application object (i.e., api.init_app(app) – doing so would place the API at the website root). However, in most applications we would rather have the API routes configured with a prefix such as /api/v1 to enforce our versioning system.

The best way to accomplish this is with Flask blueprints. Typically, blueprints are used to factor a large, monolithic Flask application into logical groupings based on the functional areas of your website. Using a blueprint to isolate the API will allow us to define a url_prefix for the API endpoints.

api_bp Blueprint

In the src/flask_api_tutorial/api/__init__.py file, add the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

"""API blueprint configuration."""
from flask import Blueprint
from flask_restx import Api

api_bp = Blueprint("api", __name__, url_prefix="/api/v1")
authorizations = {"Bearer": {"type": "apiKey", "in": "header", "name": "Authorization"}}

api = Api(
    api_bp,
    version="1.0",
    title="Flask API with JWT-Based Authentication",
    description="Welcome to the Swagger UI documentation site!",
    doc="/ui",
    authorizations=authorizations,
)

There are a few important things to note about how we are configuring the api and api_bp objects:

The next step in configuring the API is registering the api_bp blueprint with our Flask application. The correct place to do this is within the create_app method in the src/flask_api_tutorial/__init__.py file. Open this file and add the highlighted lines below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

"""Flask app initialization via factory pattern."""
from flask import Flask
from flask_bcrypt import Bcrypt
from flask_cors import CORS
from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy

from flask_api_tutorial.config import get_config

cors = CORS()
db = SQLAlchemy()
migrate = Migrate()
bcrypt = Bcrypt()


def create_app(config_name):
    app = Flask("flask-api-tutorial")
    app.config.from_object(get_config(config_name))

    from flask_api_tutorial.api import api_bp

    app.register_blueprint(api_bp)

    cors.init_app(app)
    db.init_app(app)
    migrate.init_app(app, db)
    bcrypt.init_app(app)
    return app

It’s a good idea to make sure that everything still works and we have not broken anything, so run the unit tests with tox. They should all pass. Then, run flask routes to see the new URL routes that have been registered in our application:

(flask-api-tutorial) flask-api-tutorial $ flask routes
Endpoint             Methods  Rule
-------------------  -------  --------------------------
api.doc              GET      /api/v1/ui
api.root             GET      /api/v1/
api.specs            GET      /api/v1/swagger.json
restplus_doc.static  GET      /swaggerui/<path:filename>
static               GET      /static/<path:filename>

The first four routes in the list were added by registering the api_bp blueprint with our application. Next, run flask run to start the development server and point your browser to http://localhost:5000/api/v1/ui (if you are using a different port or hostname on your dev machine, adjust accordingly).

You should see something similar to the screenshot below. Note that the URL path, API version, title and description are taken directly from values we provided to the Api constructor in the src/flask_api_tutorial/api/__init__.py file.

API Namespaces

In the same way that we can organize our Flask project with blueprints, we can organize our Flask-RESTx API with namespace objects. Our API will contain two namespaces: auth_ns and widget_ns, which correspond to the flask_api_tutorial.api.auth and flask_api_tutorial.api.widgets packages, respectively. For now, we will focus on auth_ns, since this is the namespace that handles authentication requests.

Currently, the src/flask_api_tutorial/api/auth folder only contains the __init__.py file. We need to create 3 new files in the auth folder: business.py, dto.py and endpoints.py. Run the command below from the project root folder to create the files (or create them yourself however you wish):

(flask-api-tutorial) flask-api-tutorial $ cd src/flask_api_tutorial/api/auth && touch business.py dto.py endpoints.py
(flask-api-tutorial) flask-api-tutorial/src/flask_api_tutorial/api/auth $ ls -al
total 8
drwxr-xr-x  7 aaronluna  staff  224 Dec 30 01:20 .
drwxr-xr-x  5 aaronluna  staff  160 Dec 27 02:47 ..
-rw-r--r--  1 aaronluna  staff    0 Dec 29 13:05 __init__.py
-rw-r--r--  1 aaronluna  staff    0 Dec 30 01:20 business.py
-rw-r--r--  1 aaronluna  staff    0 Dec 30 01:20 dto.py
-rw-r--r--  1 aaronluna  staff    0 Dec 30 01:20 endpoints.py

All of these files are standard for any Flask-RESTx API namespace package that I create. These files perform specific roles that are common to request handling and response formatting:

Before we begin implementing the API routes and business logic for the authentication processes, we need to understand how to parse the information sent by the client in a HTTP request.

Request Parsing and Response Marshalling

Flask-RESTx provides two different approaches for parsing and validating request data. Deciding which method to use will depend on the complexity of the data and the interface you provide to the client.

In many cases the source of an HTTP POST request is a form submission from a page. Another common scenario is an HTTP GET request that occurs when a client accesses a URL with a query string containing pertinent request data. In these cases, you should use the RequestParser class provided in the reqparse module.

If your API endpoint expects a complex object (e.g., a blog post containing full content and metadata) and the source of the reqeust data is NOT a web form (i.e., client is accessing the API programmatically), then you should use the fields module to document the format of the object and instruct the client to send the object as serialized JSON. The expected JSON format is defined as an API model, and is used both for validating request data and documenting the output format for objects returned from HTTP GET requests.

Documenting the expected format of request and response data has an additional benefit – the Swagger UI automatically documents the expected format for any API routes we specify.

Request Parser Configuration

Flask-RESTx provides the RequestParser class as a way to parse data from the Flask request object. For each value to be parsed, we add an instance of the Argument class to the RequestParser. The Argument class is very flexible and is configured by the parameters listed below:

I recommend reading and fully understanding the documentation explaining how to specify input validation for advanced and custom data types. Also, please review the API documentation for the inputs module which contains a list of advanced data types that are available before you create your own custom validator.

Defining API Models

For POST and PUT requests that create a new resource or update an existing resource in a collection, you should instruct the client to send the resource as a JSON object in the request body. You can define the expected API model by creating a dict object where the keys are the names of the attributes on the JSON object and the values are a class that will validate and convert the attribute to the required data type.

In the same way that the inputs module provides primitive data types and a set of predefined data formats to specify the type of each RequestParser Argument, the fields module fulfills the same role for model objects. You can find a list of pre-defined fields in the API documentation. You can also easily create your own custom field by subclassing fileds.Raw, as shown in the Flask-RESTx docs.

To avoid duplicating code, if you need to define two models which represent the same ORM object but expose slightly different sets of attributes, you can inherit a model rather than defining the same set of fields twice.

Response Marshalling

API models can be used to document the output of an API operation as well as the expected request format. This is most often used to return a representation of an ORM object with a subset of the attributes defined by the actual ORM model. For example, the User class includes id and password_hash attributes which store the primary key for the database table and password hash used to verify a user’s password during login. There’s very little security risk to exposing these two values, but at the bare minimum they expose implementation details which the client has no need for.

We will see this shortly in the auth/user API route which inspects the access token of the current user and returns a representation of the User object as the HTTP response. The API model we define as the expected output of this API route omits the id and password_hash attributes from the response.

auth_ns Endpoints

Within the auth_ns namespace, we will create the four API endpoints listed in the table below:

We will implement each endpoint in the same way, following the steps listed below:

This process will result in an updated Swagger UI page containing a documented version of the API endpoint which allows clients to construct data in the expected format, send HTTP requests and inspect responses from the server.

api.auth_register Endpoint

The first resource we create will handle the process of registering a new user account. If this were a full-stack tutorial, we would probably create a registration form that calls this API endpoint when a user clicks the Submit button. I’m leaving all decisions regarding the front-end in your hands, therefore designing such a form is your task to conquer.

auth_reqparser Request Parser

When a new user attempts to register, what data is required? The way our User model is defined, the value for email must be unique (i.e., two users cannot register with the same email address). The only other value which is provided by the user is their password, which is not stored in the database (the actual password is ony needed to create the password_hash value and to authenticate a user attempting to login). Open src/flask_api_tutorial/api/auth/dto.py, add the content below and save the file:

"""Parsers and serializers for /auth API endpoints."""
from flask_restx.inputs import email
from flask_restx.reqparse import RequestParser


auth_reqparser = RequestParser(bundle_errors=True)
auth_reqparser.add_argument(
    name="email", type=email(), location="form", required=True, nullable=False
)
auth_reqparser.add_argument(
    name="password", type=str, location="form", required=True, nullable=False
)

The first thing to note here is the parameter bundle_errors=True when we instantiate auth_reqparser. This value is false by default, which means that only a single error is reported whenever the request data fails validation. I prefer to have all error messages reported for all arguments in our request parser.

Next, notice that we have specified type=email() for the email argument. This is a pre-defined type provided by Flask-RESTx that verifies that the value sent in the request is a valid email address. If a request includes a value of “213323 kjljk” for email, we expect that the user will not be registered and the response will include a status code indicating that a validation error occurred and a message explaining that the value for email is not valid.

The remaining parameters are the same for both arguments: location="form", required=True, nullable=False. The purpose of each parameter was explained previously, and should answer any questions you have about these settings.

Process Registration Request

Next, we need to create a function that performs the following actions:

• Add a new user to the database
• Issue an access token for the new user
• Construct an HTTP response including the access token and send the response the client

For any response containing sensitive information (e.g., access tokens, credentials, etc), RFC6749 (OAuth 2.0) defines the required and optional fields in both the response body and header:

5.1 Successful Response

The authorization server issues an access token and optional refresh token, and constructs the response by adding the following parameters to the entity-body of the HTTP response:

access_token

REQUIRED. The access token issued by the authorization server.

token_type

REQUIRED. The type of the token issued as described in Section 7.1. Value is case insensitive.

expires_in

RECOMMENDED. The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.

refresh_token

OPTIONAL. The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in Section 6.

scope

OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED. The scope of the access token as described by Section 3.3.

The parameters are included in the entity-body of the HTTP response using the "application/json" media type as defined by [RFC4627]. The parameters are serialized into a JavaScript Object Notation (JSON) structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.

The authorization server MUST include the HTTP "Cache-Control" response header field [RFC2616] with a value of "no-store" in any response containing tokens, credentials, or other sensitive information, as well as the "Pragma" response header field [RFC2616] with a value of "no-cache".

For example:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "example",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter": "example_value"
}

Open src/flask_api_tutorial/api/auth/business.py, add the content below and save the file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

"""Business logic for /auth API endpoints."""
from http import HTTPStatus

from flask import current_app, jsonify
from flask_restx import abort

from flask_api_tutorial import db
from flask_api_tutorial.models.user import User


def process_registration_request(email, password):
    if User.find_by_email(email):
        abort(HTTPStatus.CONFLICT, f"{email} is already registered", status="fail")
    new_user = User(email=email, password=password)
    db.session.add(new_user)
    db.session.commit()
    access_token = new_user.encode_access_token()
    response = jsonify(
        status="success",
        message="successfully registered",
        access_token=access_token.decode(),
        token_type="bearer",
        expires_in=_get_token_expire_time(),
    )
    response.status_code = HTTPStatus.CREATED
    response.headers["Cache-Control"] = "no-store"
    response.headers["Pragma"] = "no-cache"
    return response


def _get_token_expire_time():
    token_age_h = current_app.config.get("TOKEN_EXPIRE_HOURS")
    token_age_m = current_app.config.get("TOKEN_EXPIRE_MINUTES")
    expires_in_seconds = token_age_h * 3600 + token_age_m * 60
    return expires_in_seconds if not current_app.config["TESTING"] else 5

Next, we need to create the API endpoint and incorporate it with the auth_reqparser and process_registration_request function.

RegisterUser Resource

If you look back at all of the material covered in this tutorial, it’s amazing (IMO) that we haven’t written one line of code that that makes our Flask application perform one of the basic functions of a web server: URL routing. It’s time to fix that.

In an application that adheres to the principles of REST, each API endpoint (IOW, each URL) is a representation of a resource. Clients interact with resources by sending HTTP requests. The method type of the client’s request (e.g., GET, PUT, POST) is used to perform different operations, and the nature of the operation should be related to the. For this reason, when we need to add a URL route to the API, we define a class that inherits from the flask_restx.Resource base class.

According to the table defining the API endpoints for the auth_ns namespace, users can register for a new account by sending a POST request to /api/v1/auth/register. To create this API endpoint, open src/flask_api_tutorial/api/auth/endpoints.py, add the content below and save the file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

"""API endpoint definitions for /auth namespace."""
from http import HTTPStatus

from flask_restx import Namespace, Resource

from flask_api_tutorial.api.auth.dto import auth_reqparser
from flask_api_tutorial.api.auth.business import process_registration_request

auth_ns = Namespace(name="auth", validate=True)


@auth_ns.route("/register", endpoint="auth_register")
class RegisterUser(Resource):
    """Handles HTTP requests to URL: /api/v1/auth/register."""

    @auth_ns.expect(auth_reqparser)
    @auth_ns.response(int(HTTPStatus.CREATED), "New user was successfully created.")
    @auth_ns.response(int(HTTPStatus.CONFLICT), "Email address is already registered.")
    @auth_ns.response(int(HTTPStatus.BAD_REQUEST), "Validation error.")
    @auth_ns.response(int(HTTPStatus.INTERNAL_SERVER_ERROR), "Internal server error.")
    def post(self):
        """Register a new user and return an access token."""
        request_data = auth_reqparser.parse_args()
        email = request_data.get("email")
        password = request_data.get("password")
        return process_registration_request(email, password)

Add auth_ns Namespace to api

In order to register the auth_ns namespace with the api object, open src/flask_api_tutorial/api/__init__.py and add the highlighted lines (Line 5 and Line 19):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

"""API blueprint configuration."""
from flask import Blueprint
from flask_restx import Api

from flask_api_tutorial.api.auth.endpoints import auth_ns

api_bp = Blueprint("api", __name__, url_prefix="/api/v1")
authorizations = {"Bearer": {"type": "apiKey", "in": "header", "name": "Authorization"}}

api = Api(
    api_bp,
    version="1.0",
    title="Flask API with JWT-Based Authentication",
    description="Welcome to the Swagger UI documentation for the Widget API",
    doc="/ui",
    authorizations=authorizations,
)

api.add_namespace(auth_ns, path="/auth")

The path parameter in the add_namespace method sets the prefix for all endpoints in the auth_ns namepsace. This, along with the url_prefix value in Line 8, is why all URL routes in the auth_ns namespace begin with /api/v1/auth.

We can verify that our route has been correctly registered by running flask routes:

flask-api-tutorial $ flask routes
Endpoint             Methods  Rule
-------------------  -------  --------------------------
api.auth_register    POST     /api/v1/auth/register
api.doc              GET      /api/v1/ui
api.root             GET      /api/v1/
api.specs            GET      /api/v1/swagger.json
restplus_doc.static  GET      /swaggerui/<path:filename>
static               GET      /static/<path:filename>

The presence of the api.auth_register endpoint in the list of routes confirms a number of things:

• The RegisterUser resource supports HTTP POST requests, and no other method types.
• RegisterUser is within the auth_ns namespace.
• Because the api_bp Blueprint object is linked with the api object AND registered with the app Flask application object, adding the auth_ns Namespace object to the api object with the add_namespace method automatically registers all routes within the namespace with the Flask application object.

Start the development server by running flask run and point your browser to http://localhost:5000/api/v1/ui to check out the Swagger UI:

You can click anywhere on the green bar to expand the component. It might not seem like a huge deal, but everything you see was automatically generated by Flask-RESTx (from the api object, auth_ns object, auth_reqparser, RegisterUser, etc):

If you’d like to send a request, click the Try It Out button. Then, enter any valid email address and any value for password and click Execute:

You should receive a response with status code 201 HTTPStatus.CREATED if the email address is formatted correctly (this is the only validation process being performed by auth_reqparser):

If you attempt to register with an email address that already exists in the database, you should receive a response with status code 409 HTTPStatus.CONFLICT. You can also test the API with a command-line tool (e.g., httpie, curl, wget, etc):

flask-api-tutorial $ http -f :5000/api/v1/auth/register email=user@test.com password=123456

POST /api/v1/auth/login HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 37
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5000
User-Agent: HTTPie/2.0.0

email=user%40test.com&password=123456

HTTP/1.0 409 CONFLICT
Access-Control-Allow-Origin: *
Content-Length: 79
Content-Type: application/json
Date: Sat, 03 Aug 2019 23:20:29 GMT
Server: Werkzeug/0.16.1 Python/3.7.6

{
  "message": "user@test.com is already registered",
  "status": "fail",
}

Here’s an example of a successful request using httpie. Note that on the command-line or Swagger UI the response from the server is always formatted as JSON:

flask-api-tutorial $ http -f :5000/api/v1/auth/register email=user2@test.com password=123456

POST /api/v1/auth/login HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 37
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5000
User-Agent: HTTPie/2.0.0

email=user2%40test.com&password=123456

HTTP/1.0 201 CREATED
Access-Control-Allow-Origin: *
Content-Length: 79
Content-Type: application/json
Date: Sat, 03 Aug 2019 23:20:29 GMT
Server: Werkzeug/0.16.1 Python/3.7.6

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1ODI5MzQwMzMsImlhdCI6MTU4MjkzMzEzMywic3ViIjoiNjcwOTVlZDUtZjdhYS00MGE3LTgzZGUtNzQ1YmMzYjA5NDFmIiwiYWRtaW4iOmZhbHNlfQ.ylvNfoWwhI-NRU2WS65t4ti6sTbOEDQcJYIQC6ua0Do",
  "expires_in": 900,
  "message": "successfully registered",
  "status": "success",
  "token_type": "bearer"
}

Everything appears to be working correctly for the /register endpoint. Next, we will figure out how to create unit tests that interact with the API.

Unit Tests: test_auth_register.py

Before we start writing test cases for the newly-created endpoint, we need to add a function to tests/util.py. Open the file and add the lines highlighted below (Lines 2, 8-13):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

"""Shared functions and constants for unit tests."""
from flask import url_for

EMAIL = "new_user@email.com"
PASSWORD = "test1234"


def register_user(test_client, email=EMAIL, password=PASSWORD):
    return test_client.post(
        url_for("api.auth_register"),
        data=f"email={email}&password={password}",
        content_type="application/x-www-form-urlencoded",
    )

Let’s take a moment and discuss the register_user function. Understanding how we are using this method to test our API is absolutely vital to successfully completing this project:

Wow, that required a lot more detail than I originally anticipated. I hope it helps you understand how the test client is used within our test cases to interact with the API. Next, create a new file test_auth_register.py in the tests folder, add the content below and save the file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

"""Unit tests for api.auth_register API endpoint."""
from http import HTTPStatus

from flask_api_tutorial.models.user import User
from tests.util import EMAIL, register_user

SUCCESS = "successfully registered"


def test_auth_register(client, db):
    response = register_user(client)
    assert response.status_code == HTTPStatus.CREATED
    assert "status" in response.json and response.json["status"] == "success"
    assert "message" in response.json and response.json["message"] == SUCCESS
    assert "token_type" in response.json and response.json["token_type"] == "bearer"
    assert "expires_in" in response.json and response.json["expires_in"] == 5
    assert "access_token" in response.json
    access_token = response.json["access_token"]
    result = User.decode_access_token(access_token)
    assert result.success
    user_dict = result.value
    assert not user_dict["admin"]
    user = User.find_by_public_id(user_dict["public_id"])
    assert user and user.email == EMAIL

In the previous post, I explained the meaning and purpose of the app and client test fixtures. In order to send and receive HTTP requests from our API, the test function must include client as a parameter.

Let’s go through the test_auth_register function and explain what is being tested:

test_auth_register verifies the “happy path” for the api.auth_register endpoint. We obviously need to test scenarios where a registration request is not successful, as well. Before we create the next test case, update test_auth_register.py to import the PASSWORD value from tests/util.py (Line 5) and define a new string value (Line 8):

1
2
3
4
5
6
7
8

"""Unit tests for api.auth_register API endpoint."""
from http import HTTPStatus

from flask_api_tutorial.models.user import User
from tests.util import EMAIL, PASSWORD, register_user

SUCCESS = "successfully registered"
EMAIL_ALREADY_EXISTS = f"{EMAIL} is already registered"

To verify the expected behavior when a registration request is sent for an email address that has already been registered, add the content below and save the file:

28
29
30
31
32
33
34
35
36
37
38
39

def test_auth_register_email_already_registered(client, db):
    user = User(email=EMAIL, password=PASSWORD)
    db.session.add(user)
    db.session.commit()
    response = register_user(client)
    assert response.status_code == HTTPStatus.CONFLICT
    assert (
        "message" in response.json and response.json["message"] == EMAIL_ALREADY_EXISTS
    )
    assert "token_type" not in response.json
    assert "expires_in" not in response.json
    assert "access_token" not in response.json

The last test case we will cover at this point is where the client submits an email address that is not in the correct format (the final version of the API will have more test cases). Let’s take a look at the actual response that is sent if the email value in a registration request is not a valid email (the example below uses httpie):

flask-api-tutorial $ http -f :5000/api/v1/auth/register email="first last" password=123456

POST /api/v1/auth/register HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 32
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5000
User-Agent: HTTPie/2.0.0

email=first+last&password=123456

HTTP/1.0 400 BAD REQUEST
Access-Control-Allow-Origin: *
Content-Length: 127
Content-Type: application/json
Date: Fri, 02 Aug 2019 17:45:40 GMT
Server: Werkzeug/0.16.1 Python/3.7.6

{
  "errors": {
    "email": "first last is not a valid email"
  },
  "message": "Input payload validation failed"
}

You might notice that none of the code we wrote for the api.auth_register endpoint generated the response above. That is because this response was automatically generated by Flask-RESTx based on the auth_reqparser we configured in src/flask_api_tutorial/api/auth/dto.py.

Whenever a request is rejected because of one or more RequestParser arguments failed validation, the format of the response will always contain a message attribute equal to “Input payload validation failed” and a an errors attribute with the value being another embedded list. The embedded list contains an entry for each argument in the parser that failed validation, with the name of the argument as the attribute name and the value equal to a message describing the failure that occurred.

The information above should make writing the test case pretty easy. Since the error message for an invalid parameter will occur in nearly every set of test cases we create, we need to add it to tests/util.py (Line 6):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

"""Shared functions and constants for unit tests."""
from flask import url_for

EMAIL = "new_user@email.com"
PASSWORD = "test1234"
BAD_REQUEST = "Input payload validation failed"


def register_user(test_client, email=EMAIL, password=PASSWORD):
    return test_client.post(
        url_for("api.auth_register"),
        data=f"email={email}&password={password}",
        content_type="application/x-www-form-urlencoded",
    )

We need to import this value into test_auth_register.py (Line 5):

1
2
3
4
5
6
7
8

"""Unit tests for api.auth_register API endpoint."""
from http import HTTPStatus

from flask_api_tutorial.models.user import User
from tests.util import EMAIL, PASSWORD, BAD_REQUEST, register_user

SUCCESS = "successfully registered"
EMAIL_ALREADY_EXISTS = f"{EMAIL} is already registered"

Next, add the content below to test_auth_register.py and save the file:

42
43
44
45
46
47
48
49
50
51
52
53

def test_auth_register_invalid_email(client):
    invalid_email = "first last"
    response = register_user(client, email=invalid_email)
    assert response.status_code == HTTPStatus.BAD_REQUEST
    assert "message" in response.json and response.json["message"] == BAD_REQUEST
    assert "token_type" not in response.json
    assert "expires_in" not in response.json
    assert "access_token" not in response.json
    assert "errors" in response.json
    assert "password" not in response.json["errors"]
    assert "email" in response.json["errors"]
    assert response.json["errors"]["email"] == f"{invalid_email} is not a valid email"

I don’t think there’s anything that needs to be explained since most of it is the same as the previous test case, and the difference in the response JSON was explained thoroughly.

There are quite a few more test cases that we need to create for the api.auth_register endpoint. I will not go through any more at this point, since you can find the full set in the github repo. Also, trying to define the necessary test coverage yourself is a very worthwhile exercise.

You should run tox to make sure the new test cases all pass and that nothing else broke because of the changes:

(flask-api-tutorial) flask-api-tutorial $ tox
GLOB sdist-make: /Users/aaronluna/Projects/flask-api-tutorial/setup.py
py37 create: /Users/aaronluna/Projects/flask-api-tutorial/.tox/py37
py37 installdeps: black, flake8, pydocstyle, pytest, pytest-black, pytest-clarity, pytest-dotenv, pytest-flake8, pytest-flask
py37 inst: /Users/aaronluna/Projects/flask-api-tutorial/.tox/.tmp/package/1/flask-api-tutorial-0.1.zip
py37 installed: alembic==1.4.0,aniso8601==8.0.0,appdirs==1.4.3,attrs==19.3.0,bcrypt==3.1.7,black==19.10b0,certifi==2019.11.28,cffi==1.14.0,chardet==3.0.4,Click==7.0,entrypoints==0.3,flake8==3.7.9,Flask==1.1.1,flask-api-tutorial==0.1,Flask-Bcrypt==0.7.1,Flask-Cors==3.0.8,Flask-Migrate==2.5.2,flask-restx==0.1.1,Flask-SQLAlchemy==2.4.1,idna==2.9,importlib-metadata==1.5.0,itsdangerous==1.1.0,Jinja2==2.11.1,jsonschema==3.2.0,Mako==1.1.1,MarkupSafe==1.1.1,mccabe==0.6.1,more-itertools==8.2.0,packaging==20.1,pathspec==0.7.0,pluggy==0.13.1,py==1.8.1,pycodestyle==2.5.0,pycparser==2.19,pydocstyle==5.0.2,pyflakes==2.1.1,PyJWT==1.7.1,pyparsing==2.4.6,pyrsistent==0.15.7,pytest==5.3.5,pytest-black==0.3.8,pytest-clarity==0.3.0a0,pytest-dotenv==0.4.0,pytest-flake8==1.0.4,pytest-flask==0.15.1,python-dateutil==2.8.1,python-dotenv==0.12.0,python-editor==1.0.4,pytz==2019.3,regex==2020.2.20,requests==2.23.0,six==1.14.0,snowballstemmer==2.0.0,SQLAlchemy==1.3.13,termcolor==1.1.0,toml==0.10.0,typed-ast==1.4.1,urllib3==1.25.8,wcwidth==0.1.8,Werkzeug==0.16.1,zipp==3.0.0
py37 run-test-pre: PYTHONHASHSEED='1825844209'
py37 run-test: commands[0] | pytest
================================================= test session starts ==================================================
platform darwin -- Python 3.7.6, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 -- /Users/aaronluna/Projects/flask-api-tutorial/.tox/py37/bin/python
cachedir: .tox/py37/.pytest_cache
rootdir: /Users/aaronluna/Projects/flask-api-tutorial, inifile: pytest.ini
plugins: clarity-0.3.0a0, black-0.3.8, dotenv-0.4.0, flask-0.15.1, flake8-1.0.4
collected 52 items

run.py::FLAKE8 PASSED                                                                                            [  1%]
run.py::BLACK PASSED                                                                                             [  3%]
setup.py::FLAKE8 PASSED                                                                                          [  5%]
setup.py::BLACK PASSED                                                                                           [  7%]
src/flask_api_tutorial/__init__.py::FLAKE8 PASSED                                                                [  9%]
src/flask_api_tutorial/__init__.py::BLACK PASSED                                                                 [ 11%]
src/flask_api_tutorial/config.py::FLAKE8 PASSED                                                                  [ 13%]
src/flask_api_tutorial/config.py::BLACK PASSED                                                                   [ 15%]
src/flask_api_tutorial/api/__init__.py::FLAKE8 PASSED                                                            [ 17%]
src/flask_api_tutorial/api/__init__.py::BLACK PASSED                                                             [ 19%]
src/flask_api_tutorial/api/auth/__init__.py::FLAKE8 PASSED                                                       [ 21%]
src/flask_api_tutorial/api/auth/__init__.py::BLACK PASSED                                                        [ 23%]
src/flask_api_tutorial/api/auth/business.py::FLAKE8 PASSED                                                       [ 25%]
src/flask_api_tutorial/api/auth/business.py::BLACK PASSED                                                        [ 26%]
src/flask_api_tutorial/api/auth/dto.py::FLAKE8 PASSED                                                            [ 28%]
src/flask_api_tutorial/api/auth/dto.py::BLACK PASSED                                                             [ 30%]
src/flask_api_tutorial/api/auth/endpoints.py::FLAKE8 PASSED                                                      [ 32%]
src/flask_api_tutorial/api/auth/endpoints.py::BLACK PASSED                                                       [ 34%]
src/flask_api_tutorial/api/widgets/__init__.py::FLAKE8 PASSED                                                    [ 36%]
src/flask_api_tutorial/api/widgets/__init__.py::BLACK PASSED                                                     [ 38%]
src/flask_api_tutorial/models/__init__.py::FLAKE8 PASSED                                                         [ 40%]
src/flask_api_tutorial/models/__init__.py::BLACK PASSED                                                          [ 42%]
src/flask_api_tutorial/models/user.py::FLAKE8 PASSED                                                             [ 44%]
src/flask_api_tutorial/models/user.py::BLACK PASSED                                                              [ 46%]
src/flask_api_tutorial/util/__init__.py::FLAKE8 PASSED                                                           [ 48%]
src/flask_api_tutorial/util/__init__.py::BLACK PASSED                                                            [ 50%]
src/flask_api_tutorial/util/datetime_util.py::FLAKE8 PASSED                                                      [ 51%]
src/flask_api_tutorial/util/datetime_util.py::BLACK PASSED                                                       [ 53%]
src/flask_api_tutorial/util/result.py::FLAKE8 PASSED                                                             [ 55%]
src/flask_api_tutorial/util/result.py::BLACK PASSED                                                              [ 57%]
tests/__init__.py::FLAKE8 PASSED                                                                                 [ 59%]
tests/__init__.py::BLACK PASSED                                                                                  [ 61%]
tests/conftest.py::FLAKE8 PASSED                                                                                 [ 63%]
tests/conftest.py::BLACK PASSED                                                                                  [ 65%]
tests/test_auth_register.py::FLAKE8 PASSED                                                                       [ 67%]
tests/test_auth_register.py::BLACK PASSED                                                                        [ 69%]
tests/test_auth_register.py::test_auth_register PASSED                                                           [ 71%]
tests/test_auth_register.py::test_auth_register_email_already_registered PASSED                                  [ 73%]
tests/test_auth_register.py::test_auth_register_invalid_email PASSED                                             [ 75%]
tests/test_config.py::FLAKE8 PASSED                                                                              [ 76%]
tests/test_config.py::BLACK PASSED                                                                               [ 78%]
tests/test_config.py::test_config_development PASSED                                                             [ 80%]
tests/test_config.py::test_config_testing PASSED                                                                 [ 82%]
tests/test_config.py::test_config_production PASSED                                                              [ 84%]
tests/test_user.py::FLAKE8 PASSED                                                                                [ 86%]
tests/test_user.py::BLACK PASSED                                                                                 [ 88%]
tests/test_user.py::test_encode_access_token PASSED                                                              [ 90%]
tests/test_user.py::test_decode_access_token_success PASSED                                                      [ 92%]
tests/test_user.py::test_decode_access_token_expired PASSED                                                      [ 94%]
tests/test_user.py::test_decode_access_token_invalid PASSED                                                      [ 96%]
tests/util.py::FLAKE8 PASSED                                                                                     [ 98%]
tests/util.py::BLACK PASSED                                                                                      [100%]

=================================================== warnings summary ===================================================
src/flask_api_tutorial/api/auth/business.py::FLAKE8
  /Users/aaronluna/Projects/flask-api-tutorial/.tox/py37/lib/python3.7/site-packages/flask_restx/model.py:12: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3,and in 3.9 it will stop working
    from collections import OrderedDict, MutableMapping

src/flask_api_tutorial/api/auth/business.py::FLAKE8
  /Users/aaronluna/Projects/flask-api-tutorial/.tox/py37/lib/python3.7/site-packages/flask_restx/api.py:28: DeprecationWarning: The import 'werkzeug.cached_property' is deprecated and will be removed in Werkzeug 1.0. Use 'from werkzeug.utils import cached_property' instead.
    from werkzeug import cached_property

src/flask_api_tutorial/api/auth/business.py::FLAKE8
  /Users/aaronluna/Projects/flask-api-tutorial/.tox/py37/lib/python3.7/site-packages/flask_restx/swagger.py:12: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3,and in 3.9 it will stop working
    from collections import OrderedDict, Hashable

-- Docs: https://docs.pytest.org/en/latest/warnings.html
=========================================== 52 passed, 3 warnings in 14.47s ============================================
_______________________________________________________ summary ________________________________________________________
  py37: commands succeeded
  congratulations :)

The warning that is generated from Flask-RESTx is a very minor issue with the manner in which one of their modules is importing a type from the standard library. This has no effect on the operation of the API and will be fixed very soon in an upcoming release. I will update this test result when it has been fixed.

Checkpoint

Once again, we only implemented a small number of features from the requirements list. It’s not too surprising if you realize we only created one of the four auth_ns endpoints in this section. I think we have fully satisfied one requirement: New users can register by providing an email address and password, and partially satisfied one more since the JWT is sent in the registration and login response: JWT is sent in access_token field of HTTP response after successful authentication with email/password.

In the next section we will create the remaining three auth_ns endpoints, so the entire set of JWT authentication requirements should be complete at the next checkpoint. Questions/comments are appreciated!