FastAPI: the ultimate web framework for Python

October 18, 2023

FastAPI: the ultimate web framework for Python

Here's an article to help you start with the essentials of FastAPI, a very powerful yet simple framework. It's a clear trend in the industry.

What is FastAPI ?

FastAPI is a modern, fast web framework for building APIs with Python. It is built on top of the Starlette framework and relies on Python's type annotations to provide fast and efficient validation, serialization and documentation of API requests and responses.

What are the main features of FastAPI ?

Fast performance : FastAPI is built with high-performance libraries such as Pydantic and Uvicorn to achieve incredible speeds and handle high traffic loads.
Simple and easy-to-use
Easy validation and serialization: FastAPI uses Python's type hints to automatically validate API requests and responses, as well as to automatically serialize and deserialize data to and from JSON.
Built-in documentation: FastAPI automatically generates interactive API documentation.
ASGI support: FastAPI is built on top of ASGI (Asynchronous Server Gateway Interface), allowing it to leverage the power of asynchronous programming for even faster performance.
Dependency Injection: FastAPI makes use of Python's dependency injection system to automatically inject dependencies into API endpoints and other components, making it easy to build complex applications.

Since there are lots of articles related to FastAPI and since the framework has many interesting features (it is impossible to cover everything in a single post), I will focus primarily in:

How to create an api to do CRUD operations for airport codes (using PostgreSQL and SQLAlchemy)
Data validation using Pydantic models.
Automatic generation of API docs
Dependency Injection

I will leave for another post:

FastAPI async capabilities (including SQLAlchemy)
Build an app with FastAPI and Streamlit

. . .

Airport codes with FastAPI

Let's create a simple application to insert, update and delete airport codes into a PostgreSQL database.

You can find the source code on this repository. Once you have clone the repo, go to that directory and:

python3 -m venv venv
source venv/bin/activate

pip3 install -r requirements.txt

This will leave your environment ready for deployment. You will also need PostgreSQL installed (please check the README file ).

Let's start with the SQLAlchemy Airport model:

Nothing fancy, just a few properties for the Airport model. We can define here the name of the DB table as well as the key column(s).

Now the Pydantic model: this will be used as a Response model for the return type for the APIs. This is what I'm telling to my API users: "listen, I'm giving this model in return".

In very simple terms I'm declaring that iata_code is string and it's mandatory, but the icao_code is not (look at the str | None definition). FastAPI will use this return type to:

Validate the returned data.

If the data is invalid (e.g. you are missing a field), it means your app code is broken, not returning what it should, and it will return a server error instead of returning incorrect data. This way you and your clients can be certain that they will receive the data and the data shape expected.

Add a JSON schema for the response, in the OpenAPI path operation.

This will be used by the automatic docs.
It will also be used by automatic client code generation tools.

Limit and filter the output data to what is defined in the return type.

This is particularly important for security.

Modular App structure

When writing an app it is best to create independent and modular python code.

Ideally, you should only have to define your database models once. Using SQLAlchemy's declarative_base() and Base.metadata.create_all() allows you to write just one class per table to use in the app and to use in the database. With a separate database.py and airport.py files, we establish our connection and database table classes a single time, then call them later as needed.

Database.py

This is the module in charge of creation the database connection with SQLAlchemy

Take a look at line 16: SQLAlchemy includes a helper object that helps with the establishment of user-defined Session scopes. This is useful for eliminating threading issues across your app. The sessionmaker function is the one responsible of creating new sessions by requesting a connection to the engine and attaching it to the new Session object.

The declarative_base() base class contains a Metadata object where newly defined Table objects are collected. This Metadata object is accessed when we call the line

model.airport.Base.metadata.create_all(bind=engine)

to create our only table.

Main.py

Now: the main module, where we create the app and we bring all the modular components together.

several things here to mark.

The app variable (in line 15) will be an instance of the class FastAPI. the This will be the main point of interaction to create all your API.
This app variable is the same one referred by uvicorn in the command, when you will start the app:

uvicorn main:app --reload

The FastAPI docs include a get_db() function that allows a route to use the same session through a request and then close it when the request is finished. Then the get_db() creates a new session for the next request.
Creating a path operation: "path" here refers to the last part of the URL starting from the first / . And "operation" here refers to one of the HTTP methods:

POST : to create data.
GET: to read data.
PUT: to update data.
DELETE: to delete data.
and the more exotic ones ( OPTIONS , HEAD, PATCH , TRACE).

All the data validation is performed under the hood by Pydantic - so you get all the benefits from it.
In line 31 we can see a "path operation decorator":

@app.get("/airports/", response_model=List[AirportBase])

The @app.get("/airports/"...) tells FastAPI that the function right below is in charge of handling requests that go to:

the path /airports
using a get operation

We're also defining the response model as a List of AirportBase model.

In line 32 the python function get_airports:

def get_airports(db: Session = Depends(get_db)) -> List[AirportBase]:
    return db.query(Airport).all()

uses a dependency injection (a widely used design pattern in other programming languages) of the db Session, which will be used to query the database, through SQLAlchemy. The response is a list of all the airport codes in the database.

Path parameters

Take a look at line 38, the get_airport function:

@app.get('/airport/{code}',
         responses={404: {'description': 'Airport not found'}})
def get_airport(code: str = Path(description='IATA Airport Code'), db: Session = Depends(get_db)) -> AirportBase:

Here we're declaring a path parameter, the value of the parameter code will be passed to the function as the argument code . We're also telling the function what type of parameter is ( str in this case)
At the same time the value will be validated. Let's suppose I have defined code as an int : as soon as we go to our browser and type http://localhost:8000/airport/yul we will receive an error.

Query parameters

Whenever you declare other function parameters that are not part of the path parameters, they are automatically interpreted as "query" parameters.

You can see on line 52, on the create_airport function:

@app.post('/airport', status_code=201)
async def create_airport(iata_code: Annotated[str, Query(description='IATA Airport code', max_length=3)],
                         name: Annotated[str, Query(description='Airport name', max_length=250)],
                         city: Annotated[str, Query(description='City name', max_length=30)],
                         icao_code: Annotated[str | None, Query(description='ICAO Airport code', max_length=4)] = None,

Here, using the Annotated type (in Python 3.9 and above is part of the standard library) , we define metadata for our iata_code parameter: we're declaring it as a str, we're giving it a description and we're limiting the length to 3. Also we're saying to FastAPI this parameter is mandatory.

FastAPI will now:

Validate the data making sure the max length is 3 characters.
Show a clear error for the client when the data is not valid.
Document the parameter in the OpenAPI schema path operation (so it will show up in the automatic doc UI)

And for our icao_code parameter we define it as optional ( str|None ) and is set by default to None.

Before starting our app you will need to create an .env file on the root of your project and add these parameters:

POSTGRES_PASSWORD='postgres'
POSTGRES_USER='postgres'
POSTGRES_DB='ms-airports'
POSTGRES_HOST='localhost'

. . .

Starting the app

Time to start our app

uvicorn main:app --reload

You can see in the main module we have CRUD operations defined:

getting a list of airports
getting a particular airport by its code
creating a new airport code
deleting an existing airport code.

Let's check the built-in swagger documentation: I am completely blown away when I see the documentation page at http://localhost:8000/docs :

There is an automative interactive API where you can try each of the operations described.

Let's create an airport code using the POST method, and then let's look for that same airport code using the GET method:

The path or query parameters, header and response have our custom description or schema:

If you click "Try it out", you can fill in the parameters and headers and call the endpoint with them. It's a very convenient way to test the API endpoints with the Swagger UI.

I love Python's power and simplicity, especially when combined with a fast, modern web framework like FastAPI.

. . .

Dockerize

Now let's dockerize our FastAPI application so it can be used in local development and also for deployment on a platform. These are the 2 Dockerfile you need, first for the app:

Then for the DB:

and the docker-compose you will also need.

To deploy it on Docker your .env file should look like this:

POSTGRES_PASSWORD='postgres'
POSTGRES_USER='postgres'
POSTGRES_DB='ms-airports'
POSTGRES_HOST='db'

Now you're ready to build and deploy 🚀

docker-compose build

and:

docker-compose up

You will find your app running on http://localhost:8008/docs

. . .

Recap

With FastAPI, by using short, intuitive and standard Python type declarations, you get:

Editor support: error checks, autocompletion, etc.
Data "parsing"
Data validation
API annotation and automatic documentation

And you only have to declare them once.

That's probably the main visible advantage of FastAPI compared to alternative frameworks (apart from the raw performance)

There are much more features in FastAPI, including the security, Routers, CORS middleware and the async side of FastAPI, I invite you to read the references below.

In any case I hope you liked this post. Again you can find the source code on this repository

References:

Search This Blog

Claudio's Blog