The software specimen for this chapter is a prototypical administrator-managed online academic discussion forum, which is an academic discussion hub where alumni, teachers, and students can exchange ideas. The prototype is working but it is open for changes, so you can tweak the code while reading this chapter. It is not designed to use any database management system, but all the data is temporarily stored in various Python collections. All the applications in this book are compiled and run using Python 3.8. Codes are all uploaded at https://github.com/PacktPublishing/Building-Python-Microservices-with-FastAPI/tree/main/ch01.

The FastAPI framework is a fast, seamless, and robust Python framework but can only work on Python versions 3.6 and above. The Integrated Development Environment (IDE) used in this reference is Visual Studio Code (VS Code), which is an open source tool that we can download from this site: https://code.visualstudio.com/. Just be sure to install the VSC extensions such as Python, Python for VS Code, Python Extension Pack, Python Indent, and Material Icon Theme to provide your editor syntax checking, syntax highlighting, and other editor support.

After the successful installation of Python and VS Code, we can now install FastAPI using a terminal console. To ensure correct installation, first update Python’s package installer (pip) by running this command:

python -m pip install --upgrade pip

Afterward, we install the framework by running this series of commands:

pip install fastapi
pip install uvicorn[standard]
pip install python-multipart

Important note

If you need to install the complete FastAPI platform, including all optional dependencies, the appropriate command is pip install fastapi[all]. Likewise, if you want to install and utilize the full-blown uvicorn server, you should run the pip install uvicorn command. Also, install the bcrypt module for encryption-related tasks.

At this point, you should have installed all the needed FastAPI module dependencies from the pydantic and starlette module components in your Python environment. Furthermore, the python-multipart module is required to create a REST API that handles form parameters. The installed uvicorn, however, is an ASGI-based server that will run your FastAPI applications. The Asynchronous Server Gateway Interface (ASGI) server that FastAPI uses makes it the fastest Python framework at the time of writing. The uvicorn server has the capability to run both synchronous and asynchronous services.

After the installation and configuration of the essential tools, modules, and IDE, let us now start our first API implementation using the framework.

Learning how to create applications using FastAPI is easy and straightforward. A simple application can be created just by creating a main.py file inside your /ch01 project folder. In our online academic discussion forum, for instance, the application started with this code:

from fastapi import FastAPI
app = FastAPI()

This initializes the FastAPI framework. The application needs to instantiate the core FastAPI class from the fastapi module and use app as the reference variable to the object. Then, this object is used later as a Python @app decorator, which provides our application with some features such as routes, middleware, exception handlers, and path operations.

Important note

You can replace app with your preferred but valid Python variable name, such as main_app, forum, or myapp.

Now, your application is ready to manage REST APIs that are technically Python functions. But to declare them as REST service methods, we need to decorate them with the appropriate HTTP request method provided by the path operation @app decorator. This decorator contains the get(), post(), delete(), put(), head(), patch(), trace(), and options() path operations, which correspond to the eight HTTP request methods. And these path operations are decorated or annotated on top of the Python functions that we want to handle the request and response.

In our specimen, the first sample that the REST API created was this:

@app.get("/ch01/index")
def index():
    return {"message": "Welcome FastAPI Nerds"} 

The preceding is a GET API service method that returns a JSON object. To locally run our application, we need to execute the following command:

uvicorn main:app --reload

This command will load the forum application to the uvicorn live server through the application’s main.py file with FastAPI object referencing. Live reload is allowed by adding the --reload option, which enables the restart of the development server whenever there are changes in the code.

Figure 1.1 – The uvicorn console log

Figure 1.1 shows that uvicorn uses localhost to run the application with the default port 8000. We can access our index page through http://localhost:8000/ch01/index. To stop the server, you just need to press the Ctrl + C keyboard keys.

After running our first endpoint, let us now explore how to implement the other types of HTTP methods, namely POST, DELETE, PUT, and PATCH.

The Representation State Transfer (REST) API makes up the rules, processes, and tools that allow interaction among microservices. These are method services that are identified and executed through their endpoint URLs. Nowadays, focusing on API methods before building a whole application is one of the most popular and effective microservices design strategies. This approach, called an API-first microservices development, focuses first on the client’s needs and then later identifies what API service methods we need to implement for these client requirements.

In our online academic discussion forum app, software functionality such as user sign-up, login, profile management, message posting, and managing post replies are some of the crucial needs we prioritized. In a FastAPI framework, these features are implemented as services using functions that are defined using Python’s def keyword, with the association of the appropriate HTTP request method through the path operations provided by @app.

The login service, which requires username and password request parameters from the user, is implemented as a GET API method:

@app.get("/ch01/login/")
def login(username: str, password: str):
    if valid_users.get(username) == None:
        return {"message": "user does not exist"}
    else:
        user = valid_users.get(username)
        if checkpw(password.encode(), 
                   user.passphrase.encode()):
            return user
        else:
            return {"message": "invalid user"}

This login service uses bcrypt’s checkpw() function to check whether the password of the user is valid. Conversely, the sign-up service, which also requires user credentials from the client in the form of request parameters, is created as a POST API method:

@app.post("/ch01/login/signup")
def signup(uname: str, passwd: str):
    if (uname == None and passwd == None):
        return {"message": "invalid user"}
    elif not valid_users.get(uname) == None:
        return {"message": "user exists"}
    else:
        user = User(username=uname, password=passwd)
        pending_users[uname] = user
        return user

Among the profile management services, the following update_profile() service serves as a PUT API service, which requires the user to use an entirely new model object for profile information replacement and the client’s username to serve as the key:

@app.put("/ch01/account/profile/update/{username}")
def update_profile(username: str, id: UUID, 
                     new_profile: UserProfile):
    if valid_users.get(username) == None:
        return {"message": "user does not exist"}
    else:
        user = valid_users.get(username)
        if user.id == id:
            valid_profiles[username] = new_profile
            return {"message": "successfully updated"}
        else:
            return {"message": "user does not exist"}

Not all services that carry out updates are PUT API methods, such as the following update_profile_name() service, which only requires the user to submit a new first name, last name, and middle initial for partial replacement of a client’s profile. This HTTP request, which is handier and more lightweight than a full-blown PUT method, only requires a PATCH action:

@app.patch("/ch01/account/profile/update/names/{username}")
def update_profile_names(username: str, id: UUID, 
                          new_names: Dict[str, str]):
    if valid_users.get(username) == None:
        return {"message": "user does not exist"}
    elif new_names == None:
        return {"message": "new names are required"}
    else:
        user = valid_users.get(username)
        if user.id == id:
            profile = valid_profiles[username]
            profile.firstname = new_names['fname']
            profile.lastname = new_names['lname']
            profile.middle_initial = new_names['mi']
            valid_profiles[username] = profile
            return {"message": "successfully updated"}
        else:
            return {"message": "user does not exist"}

The last essential HTTP services that we included before building the application are the DELETE API methods. We use these services to delete records or information given a unique identification, such as username and a hashed id. An example is the following delete_post_discussion() service that allows a user to delete a posted discussion when given a username and the UUID (Universally Unique Identifier) of the posted message:

@app.delete("/ch01/discussion/posts/remove/{username}")
def delete_discussion(username: str, id: UUID):
    if valid_users.get(username) == None:
        return {"message": "user does not exist"}
    elif discussion_posts.get(id) == None:
        return {"message": "post does not exist"}
    else:
        del discussion_posts[id] 
        return {"message": "main post deleted"}

All path operations require a unique endpoint URL in the str format. A good practice is to start all URLs with the same top-level base path, such as /ch01, and then differ when reaching their respective subdirectories. After running the uvicorn server, we can check and validate whether all our URLs are valid and running by accessing the documentation URL, http://localhost:8000/docs. This path will show us a OpenAPI dashboard, as shown in Figure 1.2, listing all the API methods created for the application. Discussions on the OpenAPI will be covered in Chapter 9, Utilizing Other Advanced Features.

Figure 1.2 – A Swagger OpenAPI dashboard

After creating the endpoint services, let us scrutinize how FastAPI manages its incoming request body and the outgoing response.