Starting Flask

Flask, just like all other Python libraries, is installable from the Python Package Index (PPI) and is really easy to setup and start developing with, and it only takes a few minutes to getting started with Flask. To be able to follow this book, you should be familiar with Python, command line (or at least PIP), and MySQL.

The preceding code imports the Flask library, initiates the application by creating an instance of the Flask class, declares the route, and then defines the function to execute when the route is called. This code is enough to start your first Flask application.

The following code launches a very simple built-in server, which is good enough for testing but probably not when you want to go in production, but we will cover that in the later chapters.

When this application starts, the index route upon request shall return “Hello From Flask!” as shown in Figure 1-1.

Flask Components Covered in This Book

Now that you have been introduced to Flask, we will discuss the components that we’ll cover in Flask REST API development in this book.

This book will serve as a practical guide to REST API development using Flask, and we’ll be using MySQL as the backend database. As already discussed, Flask doesn’t come with native database access support, and to bridge that gap, we’ll use a Flask extension called Flask-SQLAlchemy which adds support for SQLAlchemy in Flask. SQLAlchemy is essentially a Python SQL toolkit and Object Relational Mapper which provides the developers the full power and flexibility of SQL.

SQLAlchemy provides full support for enterprise-level design patterns and is designed for high-performing database access while maintaining efficiency and ease of use. We’ll build a user authentication module, CRUD (Create, Read, Update, and Delete) REST APIs for object creation, retrieval, manipulation, and deletion. We’ll also integrate a documentation utility called Swagger for creating API documentation, write unit and integration tests, learn application debugging, and, finally, check out different methods of deploying and monitoring our REST APIs on cloud platforms for production use.

For unit tests, we’ll use pytest which is a full-featured Python testing tool—pytest is easy to write tests with and yet is scalable to support complex use cases. We’ll also use Postman which is a complete REST API Platform—Postman provides integration tools for every stage of the API lifecycle, making API development easier and more reliable.

API deployment and monitoring are critical parts of REST API development; development paradigm changes drastically when it comes to scaling the APIs for production use cases, and for the sake of this book, we’ll deploy our REST APIs using uWSGI and Nginx on a cloud Ubuntu server. We’ll also deploy our REST APIs on Heroku which is a cloud platform that facilitates Flask app deployment and scaling out of the box.

Last but not least, we’ll discuss debugging common Flask errors and warnings and debugging Nginx requests and check out Flask application monitoring ensuring least amount on the downtime for production use.

Uniform Interface

RESTful services should have a uniform interface to access resources, and as the name suggests, APIs’ interface for the system should be uniform across the system. A logical URI system with uniform ways to fetch and manipulate data is what makes REST easy to work with. HTTP/1.1 provides a set of methods to work on noun-based resources; the methods are generally called verbs for this purpose.

Representations

RESTful services focus on resources and providing access to the resources. A resource can be easily thought of as an object in OOP. The first thing to do while designing RESTful services is identifying different resources and determining the relation between them. A representation is a machine-readable explanation defining the current state of a resource.

Once the resources are identified, representations are the next course of action. REST provides us the ability to use any format for representing the resources in the system. Unlike SOAP which restricts us to use XML to represent the data, we can either use JSON or XML. Usually, JSON is the preferred method for representing the resources to be called by mobile or web clients, but XML can be used to represent more complex resources.

Messages

In REST architecture, which essentially established client–server style way of data communication, messages are an important key. The client and the server talk to each other via messages in which the client sends a message to the server which is often called as a request and the server sends a response. Apart from the actual data exchanged between the client and the server in the form of request and response body, there is some metadata exchanged by the client and the server both in the form of request and response headers. HTTP 1.1 defines request and response headers formats in the following way in order to achieve a uniform way of data communication across different kinds of systems (Figure 1-3).

In Figure 1-4, GET is the request method, “/comments” is the path in the server, “postId=1” is a request parameter, “HTTP/1.1” is the protocol version that the client is requesting, “jsonplaceholder.typicode.com” is the server host, and content type is a part of the request headers. All of these combined is what makes a HTTP request that the server understands.

In the preceding figure, “HTTP/2” is the response HTTP version and “200” is the response code. The part below that till “cf-ray” is the response headers, and the array of post comments below “cf-ray” is the response body of the request.

Links Between Resources

Caching

Caching is a technique that stores a copy of a given resource and serves it back when requested, saving extra DB calls and processing time. It can be done at different levels like the client, the server, or a middleware proxy server. Caching is an important tool for increasing the API performance and scaling the application; however, if not managed properly, it results in the client being served old results. Caching in REST APIs is controlled using HTTP headers. Cache headers have been an essential part of HTTP header specifications and have been an important part of scaling web services with efficiency. In REST specification, when a safe method is used on a resource URL, usually the reverse proxy caches the results to use the cached data when the same resource is requested the next time.

Stateless

Statelessness here means that every HTTP response is a complete entity in itself and enough to serve the purpose of providing information to be executed without any need of another HTTP request. The point of statelessness is to defeat the purpose of accord with the server allowing intended flexibility in the infrastructure. To facilitate the same, REST servers provide enough information in the HTTP response that the client may need. Statelessness is an essential part of being able to scale the infrastructure enabling us to deploy multiple servers to serve millions of concurrent users given the fact that there is no server session state dependency. It also enables the caching feature of REST infrastructure as it lets the caching server to decide whether to cache the request or not, just by looking at the particular request irrespective of any previous requests.

Planning REST API

So, these are the eight important things to ensure while planning your API and are really crucial for developing a stable, production-focused API system.

API Design

Now let’s look into API design. Here we’ll cover the standards of designing REST APIs keeping in mind the list of things we just talked about.

Working with PIP

PIP is a PyPi recommended tool for project dependency management. PIP comes preinstalled with Python if you are using Python downloaded from www.python.org .

However, if you don’t have PIP installed in your system, follow the guide here to install PIP.

The previous command will install PIP, setuptools (required for installing source distributions), and wheel.

To test your installation, you should run the following command (Figure 1-6) in your terminal (or command line in Windows):

$ python -V

$ pip -V

Choosing the IDE

Before we start writing the code, we’ll need something to write with. Throughout this book, we’ll use Visual Studio Code which is an open source and free IDE available on all major operating systems. Visual Studio Code is available to download from www.code.visualstudio.com , and it provides good support for developing Python applications with plenty of handy plugins to facilitate development. You can choose to use your own preferred text editor or IDE to follow this book (Figure 1-7).

Once we have the IDE setup, we can move to installing and setting up the virtual environment.

Understanding Python Virtual Environments

Python, just like other modern programming languages, provides a huge amount of third-party libraries and SDKs. Different applications might need various specific versions of third-party modules, and it won’t be possible for one Python installation to meet such requirements of every application. So, in the world of Python, the solution for this problem is virtual environment, which creates a separate self-contained directory tree containing a Python installation of the required version alongside the required packages.

At its core, the main purpose of a virtual environment is to create an isolated environment to contain an installation of Python and required packages for the application. There is no limit to the number of virtual environments you can create, and it’s super easy to create them.

Using Virtual Environments

In Python 2.7 we need a module called virtualenv which is installed using PIP to get started with Python virtual environments.

Note

In Python 3 the venv module comes preshipped as a part of the standard library.

To install virtualenv, type the following command in your terminal (or command line in case of Windows).

$ pip install virtualenv

Once we have the virtualenv module installed in our system, next we’ll create a new directory and create a virtual environment in it.

Now, type the following command to create a new directory and open it in your terminal.

$ mkdir pyenv && cd pyenv

The preceding command will create a directory and open it in your terminal, and then we’ll use the virtualenv module to create a new virtual environment inside the directory.

$ virtualenv venv

The previous command will use the virtualenv module and create a virtual environment called venv. You can name your virtual environment anything, but for this book, we’ll just use venv for the sake of uniformity.

Once this command stops executing, you’ll see a directory called venv. This directory will now hold your virtual environment.

The directory structure of the venv folder should be similar to the one in Figure 1-8.

Here is what each folder in the structure contains:

1. 1.

   bin: Files to interact with the virtual environment.

    
2. 2.

   include: C headers to compile the Python packages.

    
3. 3.

   lib: This folder contains a copy of the Python version and all the other third-party modules.

    

Next, there are copies of, or symlinks to, different Python tools to ensure all the Python code and commands are executed within the current environment. The important part here is the activation scripts in bin folder, which sets the shell to use the virtual environment’s Python and site packages. In order to do so, you need to activate the virtual environment by typing the following command in your terminal.

$ source venv/bin/activate

Once this command is executed, your shell prompt will be prefixed with the name of the virtual environment, just as in Figure 1-9.

Now, let’s install Flask in our virtual environment using the following command:

$ pip install flask

The preceding command should install Flask in our virtual environment. We’ll use the same code we did in our sample Flask application.

$ nano app.py

And type the following code in the nano text editor:

from flask import Flask

app = Flask(__name__)

@app.route('/')

def hello_world():

    return 'Hello, From Flask!'

Now,  try running your app.py using python app.py command.

$ FLASK_APP=app.py flask run

With the preceding command, you should be able to run the simple Flask application, and you should see similar output in your terminal (Figure 1-10).

Now, to deactivate the virtual environment, you need to execute the following command:

$ deactivate

After this command executes, (venv) prefix from the shell will go away, and if you try running the application again, it will throw an error (Figure 1-11).

So now you understand the concept of virtual environments, we can dig a little deeper and understand what’s happening inside the virtual environment.

Understanding how virtual environments work can really help you debug the application and understand the execution environment. To start with, let’s check out the Python executable with virtual environment activated and deactivated, in order to understand the basic difference.

Let’s execute the following command with virtual environment activated (Figure 1-12):

$ which python

As you see in the following figure, the shell is using virtual environment’s Python executable, and if you deactivate the environment and re-run the Python command, you’ll notice the shell is now using the system’s Python (Figure 1-13).

So once you activate the virtual environment, the $path environment variable is modified to point at our virtual environment, and thus the Python in our virtual environment is used rather than the system one. However, an important thing to notice here is that it is basically a copy of, or a symlink to, the system’s Python executable.

Installing Flask

The preceding command will install Flask in your virtual environment.