While researching API frameworks and libraries, I grew interested in the Flask framework. Flask is a very lightweight framework, allowing engineers to quickly create APIs in Python without much opinionated tooling. For example, Flask does not come installed with a database access layer or ORM, allowing engineers to pick whichever database access library they prefer. This flexibility is appealing to me because it allows me to configure and design the API to my liking. Also, working in Python is easy and allows me to quickly write API code.

In this article, I begin by describing how I structured my SaintsXCTF API, which is written in Flask. Next, I provide an overview of Flask and SQLAlchemy, an object relational mapper (ORM). Finally, I dive into my API code. You can view the code discussed in this article in my saints-xctf-api repository.

• Architectural Overview
• AWS Infrastructure
• Kubernetes Infrastructure
• React Web Application Overview
• Web Application React and TypeScript
• Web Application Redux State Configuration
• Web Application Cypress E2E Tests
• Web Application JSS Modular Design
• Flask Python API
• Flask API Testing
• Function API Using API Gateway & Lambda
• Auth API Using API Gateway & Lambda
• Database Client on Kubernetes

The SaintsXCTF API is a REST API that returns JSON structured data. One of the main design principles I used for the API is to include links in the JSON response bodies. For example, take the entrypoint of the API.

Two links are specified in the JSON response body. The fields containing links are self_link and versions_link. self_link specifies the current API endpoint, and versions_link specifies another endpoint that a user can navigate to. This allows users with no knowledge of the API structure to navigate the API without needing to reference external documentation. Following the /versions endpoint specified in the versions_link field gives the following response.

Once again, this API response provides more links to follow. I'm currently using the second version of my SaintsXCTF API, so the remainder of my endpoints exist under the /v2 route.

The root /v2 route gives a bit of metadata about the API, and also provides a link to /v2/links. If a user follows this route, they receive a list of all the top-level application endpoints in the API.

Let's say you are navigating through the API and are interested in viewing user routes. Following the /v2/users/links route returns all the user endpoints that are available, and what each endpoint is used for.

I shortened the API response for brevity. After viewing this list of API endpoints, a user can determine which ones to invoke to match their needs. Let's say you decide to invoke the GET endpoint /v2/users/<username> with the username andy. Doing so results in the following response:

Invoking the endpoint resulted in an HTTP 401 error. Many of the endpoints in my API are protected, requiring a temporary token in the Authorization header in order to access the API. If you don't supply a token or provide an invalid token, the API returns 401 and 403 errors, respectively. Providing a valid token in the HTTP request header results in the response below.

I omitted the actual API token, a JWT, from the curl command above. This time, the API responded successfully with a JSON object of my user in SaintsXCTF.

The SaintsXCTF API is a CRUD (Create Read Update Delete) REST API. Therefore, API endpoints aren't limited to GET requests. Users can also perform POST, PUT, and DELETE requests. The example below is a POST request that creates a new exercise log for my user.

One of the main objectives of the API is to make it as easy to use and navigate as possible. This not only improves the experience for other users, but also for myself as I revisit and refactor the API codebase. While adding links to the JSON responses makes the API easier to explore, there is still some information that it lacks. This includes authentication mechanisms and documentation of JSON request body structures (such as the request body JSON for the exercise log shown above). This information requires additional documentation. I am currently working on Swagger API documentation for this purpose, and will likely write about Swagger and the OpenAPI specification in a future article.

Flask is a lightweight web application framework which is commonly used to build REST APIs. Flask applications are written in Python, with the Flask library at their core. Flask doesn't do much beyond handling routing, so a lot of the API functionality comes from other libraries (such as flask-sqlalchemy for a Database ORM and flask-bcrypt for bcrypt password hashing).

In my API, SQLAlchemy is used for accessing a MySQL database. I use the flask-sqlalchemy library, which is a wrapper around SQLAlchemy, making it easier to use in a Flask application.

SQLAlchemy is an ORM and SQL database library for Python. SQLAlchemy works with many different database engines; in my case, SQLAlchemy is used to query data from MySQL.

In my saints-xctf-api repository, the Flask application exists in an api/src directory.

The top level directory of the Flask application contains configuration files and infrastructure setup. The infrastructure setup consists of an Nginx reverse-proxy server (nginx.conf), a uWSGI application server (uwsgi.ini), and Dockerfiles for each. The configuration files for Flask are discussed in the next section.

There are also several subdirectories in the Flask application. dao contains files that follow the Data Access Object (DAO) pattern¹. In essence, each DAO file consists of a class with methods which interact with the MySQL database using SQLAlchemy. model contains models for use in the SQLAlchemy ORM. Each model is a Python class that corresponds to a table in MySQL. route defines all the routes (endpoints) in the API. Each route is bound to a Python function which performs the logic needed to return a proper HTTP response. tests contains unit and integration tests for the API. utils contains reusable utility functions used throughout the API.

The configuration of my Flask application begins with a small file named main.py.

main.py is the entrypoint for the Flask application in the production environment. A uWSGI application server uses this file to run the API. main.py simply imports a variable named app from app.py. app is an instance of Flask, an object representing the Flask application. I initialize app in a create_app() function, found within app.py.

I simplified the create_app() code snippet a bit, making it easier to discuss. create_app() takes a single config_name argument, which is the environment that the Flask application is run within. For example, when run in production, the value of config_name is production. The first line, application = Flask(__name__), creates an instance of Flask. application is eventually the return value of create_app(), representing the Flask API.

The next line, application.config.from_object(config[config_name]), sets configuration key-value pairs for the Flask application. The values of the Flask configuration are environment specific. config[config_name] is a Python object with properties. config is defined in a config.py file, as shown below.

config is a dictionary where the keys are environment names and values are classes with Flask configuration properties. In a production environment, the ProductionConfig class is the configuration for my Flask application.

Back to the create_app() function, all the application.register_blueprint() invocations are used to configure routes in the API. register_blueprint() takes a Blueprint object as an argument. In Flask, a blueprint is an application component which is registered with the main Flask application². In my application, each blueprint is bound to a specific URL and contains all the endpoints under that URL.

For example, the call to application.register_blueprint(user_route) registers a user_route blueprint, which is defined in userRoute.py. The creation of the blueprint, which is assigned to the /v2/users route, is demonstrated below.

After registering blueprints for the Flask application in create_app(), I set four additional configuration variables by adding key-value pairs to the application.config dictionary. These configuration variables are separate from the ones discussed previously, such as those found in config.py, because they have the same values across all environments.

Next in create_app(), I call db.init_app(application). This line of code initializes SQLAlchemy in the Flask application. db is an instance of SQLAlchemy from the flask-sqlalchemy library, which is defined in database.py.

The next line, flask_bcrypt.init_app(application), initializes the Bcrypt password hashing algorithm with Flask. application.cli.add_command(test) adds a new command to the Flask CLI for testing the application. The CLI command is defined in a separate commands.py file and is invoked using a python -m flask test shell command.

The remainder of the create_app() function sets custom error messages for different HTTPS error codes. The custom error messages are JSON strings, all of which can be viewed in the app.py file.

The Flask API accesses data from a MySQL database using the SQLAlchemy library. SQLAlchemy contains an ORM (Object Relational Mapping), allowing applications to build Python classes representing SQL tables. Instantiated objects of these Python classes (referred to as "model classes") contain a single row of data from the database table.

Model classes in my application exist in a model directory. One example model class is User, which represents a user table in the MySQL database. This model exists in a User.py file.

Model classes extend the db.Model base class provided by SQLAlchemy. The __tablename__ field holds the name of the table in MySQL that the model is associated with. The remaining fields are the columns in the table and their associated data types. For example, one column in the user table is username, which holds a VARCHAR of length 20. username is the primary key of the user table, since every user has a unique username. This column is defined as a field in the User model object with the line username = Column(db.VARCHAR(20), primary_key=True).

I omitted a few details of the User model from the code snippet above, which I will discuss now. First, User has an __init__ constructor for converting a dictionary to an instance of the model. Second, User implements __str__ and __repr__ methods for printing out model objects cleanly in application logs. Third and finally, User implements __eq__ to compare two instances of User for equality.

For each table in the MySQL database, my API has two corresponding model classes. The naming convention for these classes is TableName and TableNameData. For example, the user table has User and UserData model classes. The reason for this structure is that the main model class has auditing columns that shouldn't be included in API response bodies. Therefore, the User model class is used to query the database, and UserData is used in API responses. Note that many APIs won't require a structure like this, and a single model class per table will suffice. The UserData class exists in a UserData file.

Data Access Objects (DAOs) are classes that interface with a data source; in the case of my API, a MySQL database. Separate DAOs are used for individual tables or multiple tables with similar business logic. All the DAOs in my application exist in a dao directory.

For business logic related to users, I have a DAO named userDao.py. userDao.py defines a single DAO class named UserDao. Most of the methods in UserDao are related to a user table, however there is also some logic that alters data in different tables. A shortened version of UserDao is shown below.

UserDao contains static methods which interact with MySQL using SQLAlchemy (the db variable is an instance of SQLAlchemy). Two different approaches are used to interact with the database. The first is to use the ORM and the second is to write SQL queries and execute them. For example, get_user_by_username() uses the ORM and the User model class to find a user in the database with a specific username. On the other hand, update_user() uses a SQL query to update a user in the database. Which approach is better is often a matter of personal preference. SQL is more expressive and easier to read for complex queries. The ORM avoids mixing SQL and Python code, and is easy to use for simple queries. The great thing about SQLAlchemy is that it offers both approaches for engineers to use.

One final note about the DAOs in my application. For inserts, updates, and deletes, my DAO methods use a function called BasicDao.safe_commit(). This is a custom function that attempts to commit one or many changes to the database as a transaction, and performs a rollback if the transaction fails. The code for this function is shown below and exists in basicDao.py

So far, we've seen how DAOs interact with the database and use SQLAlchemy model classes to retrieve, update, create, or delete data. Of course, user's of the API don't interface with the DAO directly. Instead, users call endpoints (routes) in the REST API and request operations to be performed. These endpoints are defined and configured in the route directory of my application.

Route files contain functions, each of which represents an endpoint in the API. Each file also defines a Flask blueprint - a component representing a route in the API with sub-routes attached to it. Flask blueprints are instantiated as Python objects. Blueprint objects are used to annotate functions in the route file. These annotations specify which route the function is associated with and what HTTP methods it responds to.

For example, I have a route file for all the endpoints that provide metadata about the API. These endpoints exist in a apiRoute.py file. A shortened version of the route file is shown below.

The Blueprint for the route file is assigned to the variable api_route and instantiated with a call to its constructor: Blueprint('api_route', __name__, url_prefix='/'). This blueprint is assigned to the root route in the API ('/') via the url_prefix keyword argument.

The first function, api(), configures an endpoint for the route /. The endpoint route is a combination of the url_prefix from the blueprint and the first argument to the @api_route.route() annotation. The URL prefix is / and the route annotation is /, which can be simplified to /. The methods keyword argument to @api_route.route() specifies all the HTTP methods that the endpoint responds to; in the case of the / route, only HTTP GET requests are handled.

The api() method returns a Flask Response object, representing an HTTP response. api() uses a jsonify() function from the Flask library to build this response. jsonify() takes a dictionary as an argument, converts it to JSON, and wraps that JSON in a Flask Response object. From the API user perspective, navigating to the route / returns this JSON object and a HTTP 200 success code.

The other routes in the apiRoute.py file follow a similar pattern of returning static JSON objects.

userRoute.py is a more complex route file, including dynamic JSON responses dependent on user inputs and database query results. It not only contains HTTP GET requests, but also POST, PUT, and DELETE requests. A generalized outline of userRoute.py is shown below.

At its core, userRoute.py is the same as its simpler apiRoute.py counterpart. It contains a blueprint with a URL prefix and functions associated with HTTP requests to sub-URLs. This time, functions handle multiple HTTP verbs and often require authentication.

For example, users() handles both HTTP GET and POST verbs, as specified by its decorator @user_route.route('/', methods=['GET', 'POST']). It also requires authentication, which is specified by a custom decorator @auth_required(enabled_methods=[GET]). The keyword argument enabled_methods=[GET] specifies that only GET requests require authentication; POST methods do not.

How requests are handled in users() depends on the HTTP verb, which is accessed through the request.method property. If a HTTP GET request is made, a users_get() function is invoked; if a HTTP POST request is made, a user_post() function is invoked. users_get() is shown below.

Similar to the routes in apiRoute.py, users_get() returns JSON responses generated by jsonify(). However, the logic is a bit more complex since a DAO is leveraged to get data from MySQL, specifically UserDao.get_users(). The format of the response JSON and the response status code depends on the result of UserDao.get_users(). If UserDao.get_users() unsuccessfully retrieves users from the database, it returns None. In this scenario, a status code of 500 is returned with a JSON response object describing the error. If UserDao.get_users() successfully retrieves users from the database, it returns a list of User model objects. These objects are converted into Python dictionaries, the data is cleaned, and they are returned in a JSON response body with a status code of 200.

My API has many endpoints of varying degrees of complexity, so feel free to explore them all on GitHub.

All the functions which are Flask endpoints have decorators attached to them. The decorator @<name>.route(), where <name> is replaced with the variable name of a Blueprint or Flask object, registers a function to handle requests at a specific URL. The @<name>.route() decorator is part of the Flask library.

You may have noticed that some of my routes have additional decorators. For example, the user() function, defined in userRoute.py file and displayed again below, has two additional annotations: @auth_required() and @disabled().

@auth_required() is a custom decorator that checks for a valid JWT token in the Authorization header of HTTP requests. Since most of my endpoints require authentication, placing JWT validation logic in a reusable decorator makes the codebase a lot cleaner. The code for @auth_required() is shown below and exists in a decorators.py file.

@auth_required() leverages the @functools.wraps() factory method to create a decorator. This approach is a Python convention. @auth_required() takes a single keyword argument enabled_methods, which is an optional list of HTTP methods. If enabled_methods is passed to the decorator, authentication requirements are only enforced for HTTP methods defined in the enabled_methods list. If enabled_methods is not passed to the decorator, all HTTP methods that an endpoint responds to will require authentication.

auth_required() first checks if an Authorization header exists on the incoming HTTP request. If the header does not exist, a 401 HTTP error code is returned to the user.

Next, auth_required() extracts a JWT from the Authorization header, placing it in a token variable. The value of the Authorization header follows the pattern Bearer j.w.t, where j.w.t is replaced by the JWT. This token is used in another asynchronous function authenticate(), which makes an HTTP request to an authentication route in my application. I host this route using AWS Lambda and AWS API Gateway, which I'll discuss in an upcoming article. The authentication route is defined in code as "{current_app.config['AUTH_URL']}/authenticate", with the domain name coming from the Flask configuration object, specifically the 'AUTH_URL' property. This is due to the authentication URL being unique in different environments.

authenticate() uses the response from the authentication route, stored in response, to determine if the user is permitted to use the API. The authentication API returns a JSON object with a single boolean result field. If result is true, the user is successfully authenticated. If result is false, the user is not allowed to use the API. The code is to configured to return a HTTP 403 error code to the user if result is false. Otherwise, authenticate() performs no further operations and control is passed through to the route's function handler.

@disabled() is also a custom decorator that disables a route in the API. If a user tries to call a disabled route, they receive a HTTP 403 error. The implementation of @disabled() is shown below, and exists in a decorators.py file.

Similar to @auth_required(), @disabled() is written with the @functools.wraps() factory method and accepts an optional disabled_methods keyword argument, with the same effect as the enabled_methods keyword argument in @auth_required(). If a route has the @disabled() decorator and disabled_methods isn't specified, all HTTP methods to that route are disabled and return HTTP 403 errors. If a route has the @disabled() decorator and disabled_methods is specified, only the HTTP methods in the disabled_methods list return 403 errors. All other methods continue with normal execution. In code, HTTP 403 errors are returned from the API with the abort(403) command.

Writing APIs with Flask is easy and flexible. Flask is not very opinionated, leaving engineers in control of design choices. For beginners or junior level programmers, Python is very easy to work with as well, making Flask a good option for large teams with engineers at different skill levels. All the code for my Flask API is available on GitHub.