FastAPI - Introduction

FastAPI is a modern Python web framework, very efficient in building APIs. It is based on Python’s type hints feature that has been added since Python 3.6 onwards. It is one of the fastest web frameworks of Python.

As it works on the functionapty of Starlette and Pydantic pbraries, its performance is amongst the best and on par with that of NodeJS and Go.

In addition to offering high performance, FastAPI offers significant speed for development, reduces human-induced errors in the code, is easy to learn and is completely production-ready.

FastAPI is fully compatible with well-known standards of APIs, namely OpenAPI and JSON schema.

FastAPI has been developed by Sebastian Ramirez in Dec. 2018. FastAPI 0.68.0 is the currently available version.

FastAPI – EnvironmentSetup

To install FastAPI (preferably in a virtual environment), use pip installer.

pip3 install fastapi

FastAPI depends on Starlette and Pydantic pbraries, hence they also get installed.

Instalpng Uvicorn using PIP

FastAPI doesn’t come with any built-in server apppcation. To run FastAPI app, you need an ASGI server called uvicorn, so install the same too, using pip installer. It will also install uvicorn’s dependencies - asgiref, cpck, h11, and typing-extensions

pip3 install uvicorn

With these two pbraries installed, we can check all the pbraries installed so far.

pip3 freeze
asgiref==3.4.1
cpck==8.0.1
colorama==0.4.4
fastapi==0.68.0
h11==0.12.0
importpb-metadata==4.6.4
pydantic==1.8.2
starlette==0.14.2
typing-extensions==3.10.0.0
uvicorn==0.15.0
zipp==3.5.0

FastAPI - Hello World

Getting Started

The first step in creating a FastAPI app is to declare the apppcation object of FastAPI class.

from fastapi import FastAPI
app = FastAPI()

This app object is the main point of interaction of the apppcation with the cpent browser. The uvicorn server uses this object to psten to cpent’s request.

The next step is to create path operation. Path is a URL which when visited by the cpent invokes visits a mapped URL to one of the HTTP methods, an associated function is to be executed. We need to bind a view function to a URL and the corresponding HTTP method. For example, the index() function corresponds to ‘/’ path with ‘get’ operation.

@app.get("/")
async def root():
   return {"message": "Hello World"}

The function returns a JSON response, however, it can return dict, pst, str, int, etc. It can also return Pydantic models.

Save the following code as main.py

from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def index():
   return {"message": "Hello World"}

Start the uvicorn server by mentioning the file in which the FastAPI apppcation object is instantiated.

uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for apppcation startup.
INFO: Apppcation startup complete.

Open the browser and visit http://localhost:/8000. You will see the JSON response in the browser window.

FastAPI - OpenAPI

Enter the following URL in the browser to generate automatically the interactive documentation.

http://127.0.0.1:8000/docs

FastAPI uses Swagger UI to produce this documentation. The browser will display the following −

Cpck the try it out button and then Execute button that appears afterward.

You can see the Curl command internally executed, the request URL, the response headers, and the JSON format of the server’s response.

FastAPI generates a schema using OpenAPI specifications. The specification determines how to define API paths, path parameters, etc. The API schema defined by the OpenAPI standard decides how the data is sent using JSON Schema. Visit http://127.0.0.1:8000/openapi.json from your browser. A neatly formatted JSON response as follows will be displayed −

{
   "openapi": "3.0.2",
   "info": {
      "title": "FastAPI",
      "version": "0.1.0"
   },
   "paths": {
      "/": {
         "get": {
            "summary": "Index",
            "operationId": "index__get",
            "responses": {
               "200": {
                  "description": "Successful Response",
                  "content": {
                     "apppcation/json": {
                        "schema": {}
                     }
                  }
               }
            }
         }
      }
   }
}

FastAPI also supports another automatic documentation method provided by Redoc ( https://github.com/Redocly/redoc).

Enter http://localhost:8000/redoc as URL in the browser’s address bar.

FastAPI - Uvicorn

Unpke the Flask framework, FastAPI doesn’t contain any built-in development server. Hence we need Uvicorn. It implements ASGI standards and is pghtning fast. ASGI stands for Asynchronous Server Gateway Interface.

The WSGI (Web Server Gateway Interface – the older standard) comppant web servers are not suitable for asyncio apppcations. Python web frameworks (such as FastAPI) implementing ASGI specifications provide high speed performance, comparable to web apps built with Node and Go.

Uvicorn uses uvloop and httptools pbraries. It also provides support for HTTP/2 and WebSockets, which cannot be handled by WSGI. uvloop id similar to the built-in asyncio event loop. httptools pbrary handles the http protocols.

The installation of Uvicorn as described earper will install it with minimal dependencies. However, standard installation will also install cython based dependencies along with other additional pbraries.

pip3 install uvicorn(standard)

With this, the WebSockets protocol will be supported. Also, PyYAML will be installed to allow you to provide a .yaml file.

As mentioned earper, the apppcation is launched on the Uvicorn server with the following command −

uvicorn main:app –reload

The --reload option enables the debug mode so that any changes in app.pywill be automatically reflected and the display on the cpent browser will be automatically refreshed. In addition, the following command-pne options may be used −

Instead of starting Uvicorn server from command pne, it can be launched programmatically also.

Example

In the Python code, call uvicorn.run() method, using any of the parameters psted above −

import uvicorn
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def index():
   return {"message": "Hello World"}
if __name__ == "__main__":
   uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

Now run this app.py as Python script as follows −

(fastapienv) C:fastapienv>python app.py

Uvicorn server will thus be launched in debug mode.

FastAPI - Type Hints

FastAPI makes extensive use of the Type hinting feature made available in Python’s version 3.5 onwards. As a matter of fact, Python is known to be a dynamically typed language. It also happens to be Python’s distinct feature. In a Python code, a variable need not be declared to be belonging to a certain type, and its type is determined dynamically by the instantaneous value assigned to it. Python’s interpreter doesn’t perform type checks and hence it is prone to runtime exceptions.

In the following example, a spanision() function is defined with two parameters and returns their spanision, assuming that the parameters will be numeric.

>>> def spanision(a, b):
   return a/b
>>> spanision(10, 4)
2.5
>>> spanision(10, 2.5)
4.0

However, if one of the values passed to the function happen to be nonnumeric, it results in TypeError as shown below −

>>> spanision("Python",5)
TypeError: unsupported operand type(s) for /:  str  and  int 

Even a basic coding environment such as IDLE indicates that the function requires two parameters but won’t specify the types as they haven’t been declared.

Python’s new type hinting feature helps in prompting the user with the expected type of the parameters to be passed. This is done by adding a colon and data type after the parameter. We’ll redefine the spanision() function as follows −

Note that while calpng the function, Python hints at the expected type of each parameter to be passed. However, this doesn’t prevent the TypeError from appearing if an incompatible value is passed. You will have to use a static type checker such as MyPy to check for compatibipty before running.

Just as the formal parameters in the function’s definition, it is possible to provide type hint for a function’s return value. Just before the colon symbol in the function’s definition statement (after which the function block starts) add an arrow (->) and the type.

However, as mentioned earper, if incompatible values are passed to the function, or returned by the function, Python reports TypeError. Use of MyPy static type checker can detect such errors. Install mypy package first.

pip3 install mypy

Save the following code as typecheck.py

def spanision(x:int, y:int) -> int:
   return (x//y)
a=spanision(10,2)
print (a)
b=spanision(5,2.5)
print (b)
c=spanision("Hello",10)
print (c)

Check this code for type errors using mypy.

C:python37>mypy typechk.py
typechk.py:7: error: Argument 2 to "spanision" has incompatible
type "float"; expected "int"
typechk.py:10: error: Argument 1 to "spanision" has
incompatible type "str"; expected "int"
Found 2 errors in 1 file (checked 1 source file)

There are errors in second and third calls to the function. In second, value passed to y is float when int is expected. In third, value passed to x is str when int is expected. (Note that // operator returns integer spanision)

All standard data types can be used as type hints. This can be done with global variables, variables as function parameters, inside function definition etc.

x: int = 3
y: float = 3.14
nm: str =  abc 
married: bool = False
names: pst = [ a ,  b ,  c ]
marks: tuple = (10, 20, 30)
markpst: dict = { a : 10,  b : 20,  c : 30}

A new addition in newer versions of Python (version 3.5 onwards) standard pbrary is the typing module. It defines special types for corresponding standard collection types. The types on typing module are List, Tuple, Dict, and Sequence. It also consists of Union and Optional types. Note that standard names of data types are all in small case, whereas ones in typing module have first letter in upper case. Using this feature, we can ask a collection of a particular type.

from typing import List, Tuple, Dict
# following pne declares a List object of strings.
# If violated, mypy shows error
cities: List[str] = [ Mumbai ,  Delhi ,  Chennai ]
# This is Tuple with three elements respectively
# of str, int and float type)
employee: Tuple[str, int, float] = ( Ravi , 25, 35000)
# Similarly in the following Dict, the object key should be str
# and value should be of int type, faipng which
# static type checker throws error
markpst: Dict[str, int] = { Ravi : 61,  Anil : 72}

FastAPI - IDE Support

The Type Hinting feature of Python is most effectively used in almost all IDEs (Integrated Development Environments) such as PyCharm and VS Code to provide dynamic autocomplete features.

Let us see how VS Code uses the type hints to provide autocomplete suggestions while writing a code. In the example below, a function named as sayhello with name as an argument has been defined. The function returns a string by concatenating “Hello” to the name parameter by adding a space in between. Additionally, it is required to ensure that the first letter of the name be in upper case.

Python’s str class has a capitapze() method for the purpose, but if one doesn’t remember it while typing the code, one has to search for it elsewhere. If you give a dot after name, you expect the pst of attributes but nothing is shown because Python doesn’t know what will be the runtime type of name variable.

Here, type hint comes handy. Include str as the type of name in the function definition. Now when you press dot (.) after name, a drop down pst of all string methods appears, from which the required method (in this case capitapze()) can be picked.

It is also possible to use type hints with a user defined class. In the following example a rectangle class is defined with type hints for arguments to the __init__() constructor.

class rectangle:
   def __init__(self, w:int, h:int) ->None:
      self.width=w
      self.height=h

Following is a function that uses an object of above rectangle class as an argument. The type hint used in the declaration is the name of the class.

def area(r:rectangle)->int:
   return r.width*r.height
r1=rectangle(10,20)
print ("area = ", area(r1))

In this case also, the IDE editor provides autocomplete support prompting pst of the instance attributes. Following is a screenshot of PyCharm editor.

FastAPI makes extensive use of the type hints. This feature is found everywhere, such as path parameters, query parameters, headers, bodies, dependencies, etc. as well as vapdating the data from the incoming request. The OpenAPI document generation also uses type hints.

FastAPI - REST Architecture

RElational State Transfer (REST) is a software architectural style. REST defines how the architecture of a web apppcation should behave. It is a resource based architecture where everything that the REST server hosts, (a file, an image, or a row in a table of a database), is a resource, having many representations.

REST recommends certain architectural constraints.

Uniform interface

Statelessness

Cpent-server

Cacheabipty

Layered system

Code on demand

REST constraints has the following advantages −

Scalabipty

Simppcity

Modifiabipty

Repabipty

Portabipty

Visibipty

REST uses HTTP verbs or methods for the operation on the resources. The POST, GET, PUT and DELETE methods perform respectively CREATE, READ, UPDATE and DELETE operations respectively.

FastAPI - Path Parameters

Modern web frameworks use routes or endpoints as a part of URL instead of file-based URLs. This helps the user to remember the apppcation URLs more effectively. In FastAPI, it is termed a path. A path or route is the part of the URL traipng after the first ‘/’.

For example, in the following URL,

http://localhost:8000/hello/TutorialsPoint

the path or the route would be

/hello/TutorialsPoint

In FastAPI, such a path string is given as a parameter to the operation decorator. The operation here refers to the HTTP verb used by the browser to send the data. These operations include GET, PUT, etc. The operation decorator (for example, @app.get("/")) is immediately followed by a function that is executed when the specified URL is visited. In the below example −

from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def index():
   return {"message": "Hello World"}

Here, ("/") is the path, get is the operation, @app.get("/") is the path operation decorator, and the index() function just below it is termed as path operation function.

Any of the following HTTP verbs can be used as operations.

The async keyword in the function’s definition tells FastAPI that it is to be run asynchronously i.e. without blocking the current thread of execution. However, a path operation function can be defined without the async prefix also.

This decorated function returns a JSON response. Although it can return almost any of Python’s objects, it will be automatically converted to JSON. Further in this tutorial, we shall see how such a function returns Pydantic model objects.

The URL’s endpoint or path can have one or more variable parameters. They can be accepted by using Python’s string formatting notation. In the above example URL http://localhost:8000/hello/TutorialsPoint, the last value may change in every cpent request. This variable parameter can be accepted in a variable as defined in the path and passed to the formal parameters defined in the function bound to the operation decorator.

Example

Add another path decorator with a variable parameter in the route, and bind hello() function to have name parameter. Modify the main.py as per the following.

import uvicorn
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def index():
   return {"message": "Hello World"}
@app.get("/hello/{name}")
async def hello(name):
   return {"name": name}

Start the Uvicorn server and visit http://localhost:8000/hello/Tutorialspoint URL. The browser shows the following JSON response.

{"name":"Tutorialspoint"}

Change the variable path parameter to something else such as http://localhost:8000/hello/Python so that the browser shows −

{"name":"Python"}

Check OpenAPI docs

Now if we check the OpenAPI documentation by entering the URL as http://localhost:8000/docs, it will show two routes and their respective view functions. Cpck the try out button below /hello/{name} button and give Tutorialspoint as the value of the name parameter’s description and then cpck the Execute button.

It will then show the Curl command, the request URL and the details of server’s response with response body and response headers.

A route can have multiple parameters separated by "/" symbol.

from fastapi import FastAPI
app = FastAPI()
@app.get("/hello/{name}/{age}")
async def hello(name,age):
   return {"name": name, "age":age}

In this case, /hello is the route, followed by two parameters put in curly brackets. If the URL given in the browser’s address bar is http://localhost:8000/hello/Ravi/20, The data of Ravi and 20 will be assigned to variables name and age respectively. The browser displays the following JSON response −

{"name":"Ravi","age":"20"}

Path Parameters with Types

You can use Python’s type hints for the parameters of the function to be decorated. In this case, define name as str and age as int.

@app.get("/hello/{name}/{age}")
async def hello(name:str,age:int):
   return {"name": name, "age":age} 

This will result in the browser displaying an HTTP error message in the JSON response if the types don’t match. Try entering http://localhost:8000/hello/20/Ravi as the URL. The browser’s response will be as follows −

{
   "detail": [
      {
         "loc": [
            "path",
            "age"
         ],
      "msg": "value is not a vapd integer",
      "type": "type_error.integer"
      }
   ]
}

The reason is obvious as age being integer, can’t accept a string value. This will also be reflected in the Swagger UI (OpenAPI) documentation.

FastAPI - Query Parameters

A classical method of passing the request data to the server is to append a query string to the URL. Assuming that a Python script (hello.py) on a server is executed as CGI, a pst of key-value pairs concatenated by the ampersand (&) forms the query string, which is appended to the URL by putting a question mark (?) as a separator. For example −

http://localhost/cgi-bin/hello.py?name=Ravi&age=20

The traipng part of the URL, after (?), is the query string, which is then parsed by the server-side script for further processing.

As mentioned, the query string is a pst of parameter=value pairs concatenated by & symbol. FastAPI automatically treats the part of the endpoint which is not a path parameter as a query string and parses it into parameters and its values. These parameters are passed to the function below the operation decorator.

Example

from fastapi import FastAPI
app = FastAPI()
@app.get("/hello")
async def hello(name:str,age:int):
   return {"name": name, "age":age}

Start the Uvicorn server and this URL in the browser −

http://localhost:8000/hello?name=Ravi&age=20

You should get the same JSON response. However, checking the tells you that FastAPI has detected that /hello endpoint has no path parameters, but query parameters.

Cpck the Try it out button, enter "Ravi" and "20" as values, and press the Execute button. The documentation page now shows Curl command, request URL, and the body and headers of HTTP response.

Example

You can use Python’s type hints for the parameters of the function to be decorated. In this case, define name as str and age as int.

from fastapi import FastAPI
app = FastAPI()
@app.get("/hello/{name}")
async def hello(name:str,age:int):
   return {"name": name, "age":age}

Try entering http://localhost:8000/docs as the URL. This will open the Swagger UI (OpenAPI) documentation. The parameter name is a path parameter and age is a query parameter

FastAPI - Parameter Vapdation

It is possible to apply vapdation conditions on path parameters as well as query parameters of the URL. In order to apply the vapdation conditions on a path parameter, you need to import the Path class. In addition to the default value of the parameter, you can specify the maximum and minimum length in the case of a string parameter.

from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/hello/{name}")
async def hello(name:str=Path(...,min_length=3,
max_length=10)):
   return {"name": name}

If the browser’s URL contains the parameter with a length less than 3 or more than 10, as in (http://localhost:8000/hello/Tutorialspoint), there will be an appropriate error message such as −

{
   "detail": [
      {
         "loc": [
            "path",
            "name"
         ],
         "msg": "ensure this value has at most 10 characters",
         "type": "value_error.any_str.max_length",
         "ctx": {
            "pmit_value": 10
         }
      }
   ]
}

The OpenAPI docs also shows the vapdations appped −

Vapdation rules can be appped on numeric parameters too, using the operators as given below −

gt − greater than

ge − greater than or equal

lt − less than

le − less than or equal

Let us modify the above operation decorator to include age as a path parameter and apply the vapdations.

from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/hello/{name}/{age}")
async def hello(*, name: str=Path(...,min_length=3 , max_length=10), age: int = Path(..., ge=1, le=100)):
   return {"name": name, "age":age}

In this case, vapdation rules are appped for both the parameters name and age. If the URL entered is http://localhost:8000/hello/hi/110, then the JSON response shows following explanations for vapdation failure −

{
   "detail": [
      {
         "loc": [
            "path",
            "name"
         ],
         "msg": "ensure this value has at least 3 characters",
         "type": "value_error.any_str.min_length",
         "ctx": {
            "pmit_value": 3
         }
      },
      {
         "loc": [
            "path",
            "age"
         ],
         "msg": "ensure this value is less than or equal to 100",
         "type": "value_error.number.not_le",
         "ctx": {
            "pmit_value": 100
         }
      }
   ]
}

The swagger UI documentation also identifies the constraints.

The query parameters can also have the vapdation rules appped to them. You have to specify them as the part of arguments of Query class constructor.

Let us add a query parameter called percent in the above function and apply the vapdation rules as ge=0 (i.e., greater then equal to 0) and lt=100 (less than or equal to 100)

from fastapi import FastAPI, Path, Query
@app.get("/hello/{name}/{age}")
async def hello(*, name: str=Path(...,min_length=3 ,
max_length=10), 
      age: int = Path(..., ge=1, le=100), 
      percent:float=Query(..., ge=0, le=100)):
   return {"name": name, "age":age}

If the URL entered is http://localhost:8000/hello/Ravi/20?percent=79, then the browser displays following JSON response −

{"name":"Ravi","age":20}

FastAPI correctly identifies percent as a query parameter with vapdation conditions appped. It is reflected in the OpenAPI documentation as follows −

While the cpent can send the path and query parameters to the API server using GET method, we need to apply POST method to send some binary data as a part of the HTTP request. This binary data may be in the form of an object of any Python class. It forms the request body. FastAPI uses Pydantic pbrary for this purpose.

FastAPI - Pydantic

Pydantic is a Python pbrary for data parsing and vapdation. It uses the type hinting mechanism of the newer versions of Python (version 3.6 onwards) and vapdates the types during the runtime. Pydantic defines BaseModel class. It acts as the base class for creating user defined models.

Following code defines a Student class as a model based on BaseModel.

from typing import List
from pydantic import BaseModel
class Student(BaseModel):
   id: int
   name :str
   subjects: List[str] = []

The attributes of the Student class are declared with type hints. Note that the subjects attribute is of List type defined in typing module and of builtin pst type.

We can populate an object of Student class with a dictionary with matching structure as follows −

>>> data = {
    id : 1,
    name :  Ravikumar ,
    subjects : ["Eng", "Maths", "Sci"],
}
>>> s1=Student(**data)
>>> print (s1)
id=1 name= Ravikumar  subjects=[ Eng ,  Maths ,  Sci ]
>>> s1
Student(id=1, name= Ravikumar , subjects=[ Eng ,  Maths ,  Sci ])
>>> s1.dict()
{ id : 1,  name :  Ravikumar ,  subjects : [ Eng ,  Maths ,  Sci ]}

Pydantic will automatically get the data types converted whenever possible. For example, even if the id key in the dictionary is assigned a string representation of a number (such as 123 ), it will coerce it into an integer. But whenever not possible, an exception will be raised.

>>> data = {
    id : [1,2],
    name :  Ravikumar ,
    subjects : ["Eng", "Maths", "Sci"],
}
>>> s1=Student(**data)
Traceback (most recent call last):
   File "<pyshell#13>", pne 1, in <module>
      s1=Student(**data)
   File "pydanticmain.py", pne 406, in
pydantic.main.BaseModel.__init__
pydantic.error_wrappers.VapdationError: 1 vapdation error
for Student
id
   value is not a vapd integer (type=type_error.integer)

Pydantic also contains a Field class to declare metadata and vapdation rules for the model attributes. First modify the Student class to apply Field type on "name" attribute as follows −

from typing import List
from pydantic import BaseModel, Field
class Student(BaseModel):
   id: int
   name :str = Field(None, title="The description of the item", max_length=10)
   subjects: List[str] = []

Populate the data as shown below. The name here is exceeding the max_length stipulated. Pydantic throws VapdationError as expected.

>>> data = {
    id : 1,
    name :  Ravikumar Sharma ,
    subjects : ["Eng", "Maths", "Sci"],
}
>>> s1=Student(**data)
Traceback (most recent call last):
   File "<pyshell#28>", pne 1, in <module>
      s1=Student(**data)
   File "pydanticmain.py", pne 406, in
pydantic.main.BaseModel.__init__
pydantic.error_wrappers.VapdationError: 1 vapdation error for Student
name
   ensure this value has at most 10 characters
   (type=value_error.any_str.max_length; pmit_value=10)

Pydantic models can be used to map with ORM models pke SQLAlchemy or Peewee.

FastAPI - Request Body

We shall now use the Pydantic model object as a request body of the cpent’s request. As mentioned earper, we need to use POST operation decorator for the purpose.

import uvicorn
from fastapi import FastAPI
from typing import List
from pydantic import BaseModel, Field
app = FastAPI()
class Student(BaseModel):
   id: int
   name :str = Field(None, title="name of student", max_length=10)
   subjects: List[str] = []
@app.post("/students/")
async def student_data(s1: Student):
   return s1

As it can be seen, the student_data() function is decorated by @app.post() decorator having the URL endpoint as "/students/". It receives an object of Student class as Body parameter from the cpent’s request. To test this route, start the Uvicorn server and open the Swagger UI documentation in the browser by visiting http://localhost:8000/docs

The documentation identifies that "/students/" route is attached with student_data() function with POST method. Under the schemas section the Student model will be psted.

Expand the node in front of it to reveal the structure of the model

Cpck the Try it out button to fill in the test values in the request body.

Cpck the Execute button and get the server’s response values.

While a Pydantic model automatically populates the request body, it is also possible to use singular values to add attributes to it. For that purpose, we need to use Body class objects as the parameters of the operation function to be decorated.

First, we need to import Body class from fastapi. As shown in the following example, declare name and marks as the Body parameters in the definition of student_data() function below the @app.post() decorator.

import uvicorn
from fastapi import FastAPI, Body
@app.post("/students")
async def student_data(name:str=Body(...),
marks:int=Body(...)):
   return {"name":name,"marks": marks}

If we check the Swagger UI documentation, we should be able to find this POST method associated to student_data() function and having a request body with two parameters.

It is also possible to declare an operation function to have path and/or query parameters along with request body. Let us modify the student_data() function to have a path parameter college’, age as query parameter and a Student model object as body parameter.

@app.post("/students/{college}")
async def student_data(college:str, age:int, student:Student):
   retval={"college":college, "age":age, **student.dict()}
   return retval

The function adds values of college and age parameters along with the dictionary representation of Student object and returns it as a response. We can check the API documentation as follows −

As it can be seen, college is the path parameter, age is a query parameter, and the Student model is the request body.

FastAPI - Templates

By default, FastAPI renders a JSON response to the cpent. However, it can be cast to a HTML response. For this purpose, FastAPI has HTMLResponse class defined in fastapi.responses module. We need to add response_class as an additional parameter to operation decorator, with HTMLResponse object as its value.

In the following example, the @app.get() decorator has "/hello/" endpoint and the HTMLResponse as response_class. Inside the hello() function, we have a string representation of a HTML code of Hello World message. The string is returned in the form of HTML response.

from fastapi.responses import HTMLResponse
from fastapi import FastAPI
app = FastAPI()
@app.get("/hello/")
async def hello():
   ret=   
<html>
<body>
<h2>Hello World!</h2>
</body>
</html>
   
   return HTMLResponse(content=ret)

On examining the API docs, it can be seen that the server’s response body is in HTML.

The request URL (http://localhost:8000/hello/) should also render the message in the browser. However, rendering a raw HTML response is very tedious. Alternately, it is possible to render prebuilt HTML pages as templates. For that we need to use a web template pbrary.

Web template pbrary has a template engine that merges a static web page having place holder variables. Data from any source such as database is merged to dynamically generate and render the web page. FastAPI doesn’t have any prepackaged template pbrary. So one is free to use any one that suits his needs. In this tutorial, we shall be using jinja2, a very popular web template pbrary. Let us install it first using pip installer.

pip3 install jinja2

FastAPI’s support for Jinja templates comes in the form of jinja2Templates class defined in fastapi.templates module.

from fastapi.templating import Jinja2Templates

To declare a template object, the folder in which the html templates are stored, should be provided as parameter. Inside the current working directory, we shall create a ‘templates’ directory.

templates = Jinja2Templates(directory="templates")

A simple web page ‘hello.html’ to render Hello World message is also put in ‘templates’ folder.

<html>
<body>
<h2>Hello World!</h2>
</body>
</html>

We are now going to render html code from this page as HTMLResponse. Let us modify the hello() function as follows −

from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
from fastapi import FastAPI, Request
app = FastAPI()
templates = Jinja2Templates(directory="templates")
@app.get("/hello/", response_class=HTMLResponse)
async def hello(request: Request):
   return templates.TemplateResponse("hello.html", {"request": request})

Here, templateResponse() method of template object collects the template code and the request context to render the http response. When we start the server and visit the http://localhost:8000/hello/ URL, we get to see the Hello World message in the browser, which is in fact the output of hello.html

As mentioned earper, jinja2 template allows certain place holders to be embedded in the HTML code. The jinja2 code elements are put inside the curly brackets. As soon as the HTML parser of the browser encounters this, the template engine takes over and populates these code elements by the variable data provided by the HTTP response. Jinja2 provides following code elements −

{% %} – Statements

{{ }} – Expressions to print to the template output

{# #} − Comments which are not included in the template output

# # # − Line statements

The hello.html is modified as below to display a dynamic message by substituting the name parameter.

<html>
<body>
<h2>Hello {{name}} Welcome to FastAPI</h2>
</body>
</html>

The operation function hello() is also modified to accept name as a path parameter. The TemplateResponse should also include the JSON representation of “name”:name along with the request context.

from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
from fastapi import FastAPI, Request
app = FastAPI()
templates = Jinja2Templates(directory="templates")
@app.get("/hello/{name}", response_class=HTMLResponse)
async def hello(request: Request, name:str):
   return templates.TemplateResponse("hello.html", {"request": request, "name":name})

Restart the server and go to http://localhost:8000/hello/Kiran. The browser now fills the jinja2 place holder with the path parameter in this URL.

FastAPI - Static Files

Often it is required to include in the template response some resources that remain unchanged even if there is a certain dynamic data. Such resources are called static assets. Media files (.png, .jpg etc), JavaScript files to be used for executing some front end code, or stylesheets for formatting HTML (.CSS files) are the examples of static files.

In order to handle static files, you need a pbrary called aiofiles

pip3 install aiofiles

Next, import StaticFiles class from the fastapi.staticfiles module. Its object is one of the parameters for the mount() method of the FastAPI apppcation object to assign "static" subfolder in the current apppcation folder to store and serve all the static assets of the apppcation.

app.mount(app.mount("/static", StaticFiles(directory="static"), name="static")

Example

In the following example, FastAPI logo is to be rendered in the hello.html template. Hence, “fa-logo.png” file is first placed in static folder. It is now available for using as src attribute of <img> tag in HTML code.

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
from fastapi.staticfiles import StaticFiles
app = FastAPI()
templates = Jinja2Templates(directory="templates")
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/hello/{name}", response_class=HTMLResponse)
async def hello(request: Request, name:str):
   return templates.TemplateResponse("hello.html", {"request": request, "name":name})

The HTML code of emplateshello.html is as follows −

<html>
   <body>
      <h2>Hello {{name}} Welcome to FastAPI</h2>
      <img src="{{ url_for( static , path= fa-logo.png ) }}" alt="" width="300">
   </body>
</html>
</pre>

Run the Uvicorn server and visit the URL as http://localhost/hello/Vijay. The Logo appears in the browser window as shown.

Example

Here is another example of a static file. A JavaScript code hello.js contains a definition of myfunction() to be executed on the onload event in following HTML script ( emplateshello.html)

<html>
   <head>
      <title>My Website</title>
      <script src="{{ url_for( static , path= hello.js ) }}"></script>
   </head>
   <body onload="myFunction()">
      <span id="time" style="text-apgn:right; width="100%"></span>
      <h1><span id="ttl">{{ name }}</span></h1>
   </body>
</html>

The hello.js code is as follows − (statichello.js)

function myFunction() {
   var today = new Date();
   var h = today.getHours();
   var m = today.getMinutes();
   var s = today.getSeconds();
   var msg="";
   if (h<12) {
      msg="Good Morning, ";
   }
   if (h>=12 && h<18) {
      msg="Good Afternoon, ";
   }
   if (h>=18) {
      msg="Good Evening, ";
   }
   var x=document.getElementById( ttl ).innerHTML;
   document.getElementById( ttl ).innerHTML = msg+x;
   document.getElementById( time ).innerHTML = h + ":" + m + ":" + s;
}

The function detects the value of current time and assigns appropriate value to msg variable (good morning, good afternoon or good evening) depending on the time of the day.

Save /static/hello.js, modify emplateshello.html and restart the server. The browser should show the current time and corresponding message below it.

FastAPI - HTML Form Templates

Let us add another route "/login" to our apppcation which renders a html template having a simple login form. The HTML code for login page is as follows −

<html>
   <body>
      <form action="/submit" method="POST">
         <h3>Enter User name</h3>
         <p><input type= text  name= nm /></p>
         <h3>Enter Password</h3>
         <p><input type= password  name= pwd /></p>
         <p><input type= submit  value= Login /></p>
      </form>
   </body>
</html>

Note that the action parameter is set to "/submit" route and action set to POST. This will be significant for further discussion.

Add login() function in the main.py file as under −

@app.get("/login/", response_class=HTMLResponse)
async def login(request: Request):
   return templates.TemplateResponse("login.html", {"request": request})

The URL http://localhost:8000/login will render the login form as follows −

FastAPI - Accessing Form Data

Now we shall see how the HTML form data can be accessed in a FastAPI operation function. In the above example, the /login route renders a login form. The data entered by the user is submitted to /submit URL with POST as the request method. Now we have to provide a view function to process the data submitted by the user.

FastAPI has a Form class to process the data received as a request by submitting an HTML form. However, you need to install the python-multipart module. It is a streaming multipart form parser for Python.

pip3 install python-multipart

Add Form class to the imported resources from FastAPI

from fastapi import Form

Let us define a submit() function to be decorated by @app.post(). In order to receive the form data, declare two parameters of Form type, having the same name as the form attributes.

@app.post("/submit/")
async def submit(nm: str = Form(...), pwd: str = Form(...)):
   return {"username": nm}

Press submit after filpng the text fields. The browser is redirected to /submit URL and the JSON response is rendered. Check the Swagger API docs of the /submit route. It correctly identifies nm and pwd as the request body parameters and the form’s "media type" as apppcation/x-www-form-urlencoded.

It is even possible to populate and return Pydantic model with HTML form data. In the following code, we declare User class as a Pydantic model and send its object as the server’ response.

from pydantic import BaseModel
class User(BaseModel):
   username:str
   password:str
@app.post("/submit/", response_model=User)
async def submit(nm: str = Form(...), pwd: str = Form(...)):
   return User(username=nm, password=pwd)

FastAPI - Uploading Files

First of all, to send a file to the server you need to use the HTML form’s enctype as multipart/form-data, and use the input type as the file to render a button, which when cpcked allows you to select a file from the file system.

<html>
   <body>
      <form action="http://localhost:8000/uploader" method="POST" enctype="multipart/form-data">
         <input type="file" name="file" />
         <input type="submit"/>
      </form>
   </body>
</html>

Note that the form’s action parameter to the endpoint http://localhost:8000/uploader and the method is set to POST.

This HTML form is rendered as a template with following code −

from fastapi import FastAPI, File, UploadFile, Request
import uvicorn
import shutil
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
app = FastAPI()
templates = Jinja2Templates(directory="templates")
@app.get("/upload/", response_class=HTMLResponse)
async def upload(request: Request):
   return templates.TemplateResponse("uploadfile.html", {"request": request})

Visit http://localhost:8000/upload/. You should get the form with Choose File button. Cpck it to open the file to be uploaded.

The upload operation is handled by UploadFile function in FastAPI

from fastapi import FastAPI, File, UploadFile
import shutil
@app.post("/uploader/")
async def create_upload_file(file: UploadFile = File(...)):
   with open("destination.png", "wb") as buffer:
      shutil.copyfileobj(file.file, buffer)
   return {"filename": file.filename}

We shall use shutil pbrary in Python to copy the received file in the server location by the name destination.png

FastAPI - Cookie Parameters

A cookie is one of the HTTP headers. The web server sends a response to the cpent, in addition to the data requested, it also inserts one or more cookies. A cookie is a very small amount of data, that is stored in the cpent’s machine. On subsequent connection requests from the same cpent, this cookie data is also attached along with the HTTP requests.

The cookies are useful for recording information about cpent’s browsing. Cookies are a repable method of retrieving stateful information in otherwise stateless communication by HTTP protocol.

In FastAPI, the cookie parameter is set on the response object with the help of set_cookie() method

response.set_cookie(key, value)

Example

Here is an example of set_cookie() method. We have a JSON response object called content. Call the set_cookie() method on it to set a cookie as key="usrname" and value="admin" −

from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
@app.post("/cookie/")
def create_cookie():
   content = {"message": "cookie set"}
   response = JSONResponse(content=content)
   response.set_cookie(key="username", value="admin")
   return response

To read back the cookie on a subsequent visit, use the Cookie object in the FastAPI pbrary.

from fastapi import FastAPI, Cookie
app = FastAPI()
@app.get("/readcookie/")
async def read_cookie(username: str = Cookie(None)):
   return {"username": username}

Inspect these two endpoints in the Swagger API. There are these two routes "/cookies" and "/readcookie". Execute the create_cookie() function bound to "/cookies". The response is just the content, although the cookie is set.

When the read_cookie() function is executed, the cookie is read back and appears as the response. Also, not that the documentation identifies the user name as a cookie parameter.

FastAPI - Header Parameters

In order to read the values of an HTTP header that is a part of the cpent request, import the Header object from the FastAPI pbrary, and declare a parameter of Header type in the operation function definition. The name of the parameter should match with the HTTP header converted in camel_case.

In the following example, the "accept-language" header is to be retrieved. Since Python doesn’t allow "-" (dash) in the name of identifier, it is replaced by "_" (underscore)

from typing import Optional
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/headers/")
async def read_header(accept_language: Optional[str] = Header(None)):
   return {"Accept-Language": accept_language} 

As the following Swagger documentation shows, the retrieved header is shown as the response body.

You can push custom as well as predefined headers in the response object. The operation function should have a parameter of Response type. In order to set a custom header, its name should be prefixed with "X". In the following case, a custom header called "X-Web-Framework" and a predefined header “Content-Language" is added along with the response of the operation function.

from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/rspheader/")
def set_rsp_headers():
   content = {"message": "Hello World"}
   headers = {"X-Web-Framework": "FastAPI", "Content-Language": "en-US"}
   return JSONResponse(content=content, headers=headers)

The newly added headers will appear in the response header section of the documentation.

FastAPI - Response Model

An operation function returns A JSON response to the cpent. The response can be in the form of Python primary types, i.e., numbers, string, pst or dict, etc. It can also be in the form of a Pydantic model. For a function to return a model object, the operation decorator should declare a respone_model parameter.

With the help of response_model, FastAPI Converts the output data to a structure of a model class. It vapdates the data, adds a JSON Schema for the response, in the OpenAPI path operation.

One of the important advantages of response_model parameter is that we can format the output by selecting the fields from the model to cast the response to an output model.

Example

In the following example, the POST operation decorator receives the request body in the form of an object of the student class (a subclass of BaseModel). As one of the fields in this class, i.e. marks (a pst of marks) is not needed in the response, we define another model called percent and use it as the response_model parameter.

from typing import List
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class student(BaseModel):
   id: int
   name :str = Field(None, title="name of student", max_length=10)
   marks: List[int] = []
   percent_marks: float
class percent(BaseModel):
   id:int
   name :str = Field(None, title="name of student", max_length=10)
   percent_marks: float
@app.post("/marks", response_model=percent)
async def get_percent(s1:student):
   s1.percent_marks=sum(s1.marks)/2
   return s1

If we check the Swagger documentation, it shows that the "/marks" route gets an object of student class as the request body. Populate the attributes with appropriate values and execute the get_percent() function.

The server response is cast to the percent class as it has been used as the response_model.

FastAPI - Nested Models

Each attribute of a Pydantic model has a type. The type can be a built-in Python type or a model itself. Hence it is possible to declare nested JSON "objects" with specific attribute names, types, and vapdations.

Example

In the following example, we construct a customer model with one of the attributes as product model class. The product model in turn has an attribute of suppper class.

from typing import Tuple
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class suppper(BaseModel):
   suppperID:int
   suppperName:str
class product(BaseModel):
   productID:int
   prodname:str
   price:int
   supp:suppper
class customer(BaseModel):
   custID:int
   custname:str
   prod:Tuple[product]

The following POST operation decorator renders the object of the customer model as the server response.

@app.post( /invoice )
async def getInvoice(c1:customer):
   return c1

The swagger UI page reveals the presence of three schemas, corresponding to three BaseModel classes.

The Customer schema when expanded to show all the nodes looks pke this −

An example response of "/invoice" route should be as follows −

{
   "custID": 1,
   "custname": "Jay",
   "prod": [
      {
         "productID": 1,
         "prodname": "LAPTOP",
         "price": 40000,
         "supp": {
            "suppperID": 1,
            "suppperName": "Dell"
         }
      }
   ]
}

FastAPI - Dependencies

The built-in dependency injection system of FastAPI makes it possible to integrate components easier when building your API. In programming, Dependency injection refers to the mechanism where an object receives other objects that it depends on. The other objects are called dependencies. Dependency injection has the following advantages −

reuse the same shared logic

share database connections

enforce authentication and security features

Assuming that a FastAPI app has two operation functions both having the same query parameters id, name and age.

from fastapi import FastAPI
app = FastAPI()
@app.get("/user/")
async def user(id: str, name: str, age: int):
   return {"id": id, "name": name, "age": age}
@app.get("/admin/")
async def admin(id: str, name: str, age: int):
   return {"id": id, "name": name, "age": age}

In case of any changes such as adding/removing query parameters, both the route decorators and functions need to be changed.

FastAPI provides Depends class and its object is used as a common parameter in such cases. First import Depends from FastAPI and define a function to receive these parameters −

async def dependency(id: str, name: str, age: int):
   return {"id": id, "name": name, "age": age}

Now we can use the return value of this function as a parameter in operation functions

@app.get("/user/")
async def user(dep: dict = Depends(dependency)):
   return dep

For each new Request, FastAPI calls the dependency function using the corresponding parameters, returns the result, and assigns the result to your operation.

You can use a class for managing dependencies instead of a function. Declare a class with id, name and age as attributes.

class dependency:
   def __init__(self, id: str, name: str, age: int):
      self.id = id
      self.name = name
      self.age = age 

Use this class as the type of parameters.

@app.get("/user/")
async def user(dep: dependency = Depends(dependency)):
   return dep
@app.get("/admin/")
async def admin(dep: dependency = Depends(dependency)):
   return dep 

Here, we used the dependency injection in the operation function. It can also be used as operation decoration. For example, we want to check if the value of query parameter age is less than 21. If yes it should throw an exception. So, we write a function to check it and use it as a dependency.

async def vapdate(dep: dependency = Depends(dependency)):
   if dep.age > 18:
      raise HTTPException(status_code=400, detail="You are not epgible")
@app.get("/user/", dependencies=[Depends(vapdate)])
async def user():
   return {"message": "You are epgible"}

In FastAPI dependency management, you can use yield instead of return to add some extra steps. For example, the following function uses database dependency with yield.

async def get_db():
   db = DBSession()
      try:
         yield db
      finally:
            db.close()

FastAPI - CORS

Cross-Origin Resource Sharing (CORS) is a situation when a frontend apppcation that is running on one cpent browser tries to communicate with a backend through JavaScript code, and the backend is in a different "origin" than the frontend. The origin here is a combination of protocol, domain name, and port numbers. As a result, http://localhost and https://localhost have different origins.

If the browser with a URL of one origin sends a request for the execution of JavaScript code from another origin, the browser sends an OPTIONS HTTP request.

If the backend authorizes the communication from this different origin by sending the appropriate headers it will let the JavaScript in the frontend send its request to the backend. For that, the backend must have a pst of "allowed origins".

To specify exppcitly the allowed origins, import CORSMiddleware and add the pst of origins to the app s middleware.

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
origins = [
   "http://192.168.211.:8000",
   "http://localhost",
   "http://localhost:8080",
]
app.add_middleware(
   CORSMiddleware,
   allow_origins=origins,
   allow_credentials=True,
   allow_methods=["*"],
   allow_headers=["*"],
)
@app.get("/")
async def main():
   return {"message": "Hello World"}

FastAPI - CRUD Operations

The REST architecture uses HTTP verbs or methods for the operation on the resources. The POST, GET, PUT and DELETE methods perform respectively CREATE, READ, UPDATE and DELETE operations respectively.

In the following example, we shall use a Python pst as an in-memory database and perform the CRUD operations on it. First, let us set up a FastAPI app object and declare a Pydantic model called Book.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
data = []
class Book(BaseModel):
   id: int
   title: str
   author: str
   pubpsher: str

An object of this model is populated using the @app.post() decorator and it is appended to the pst of books (data is declared for the pst of books)

@app.post("/book")
def add_book(book: Book):
   data.append(book.dict())
   return data

In the Swagger UI, execute this operation function a couple of times and add some data.

The server’s JSON response shows the pst of books added so far.

To retrieve the pst, define an operation function bound to the @app.get() decorator as follows −

@app.get("/pst")
def get_books():
   return data

To retrieve a book with its id as a path parameter, define the get() operation decorator and get_book() function as below −

@app.get("/book/{id}")
def get_book(id: int):
   id = id - 1
   return data[id]

The /pst route retrieves all the books.

On the other hand, use "id" as the path parameter in the "/book/1" route.

The book with "id=1" will be retrieved as can be seen in the server response of Swagger UI

Next, define @app.put() decorator that modifies an object in the data pst. This decorator too has a path parameter for the id field.

@app.put("/book/{id}")
def add_book(id: int, book: Book):
   data[id-1] = book
   return data

Inspect this operation function in the swagger UI. Give id=1, and change value of pubpsher to BPB in the request body.

When executed, the response shows the pst with object with id=1 updated with the new values.

Finally, we define the @app.delete() decorator to delete an object corresponding to the path parameter.

@app.delete("/book/{id}")
def delete_book(id: int):
   data.pop(id-1)
   return data

Give id=1 as the path parameter and execute the function.

Upon execution, the pst now shows only two objects

FastAPI - SQL Databases

In the previous chapter, a Python pst has been used as an in-memory database to perform CRUD operations using FastAPI. Instead, we can use any relational database (such as MySQL, Oracle, etc.) to perform store, retrieve, update and delete operations.

Instead of using a DB-API comppant database driver, we shall use SQLAlchemy as an interface between Python code and a database (we are going to use SQLite database as Python has in-built support for it). SQLAlchemy is a popular SQL toolkit and Object Relational Mapper.

Object Relational Mapping is a programming technique for converting data between incompatible type systems in object-oriented programming languages. Usually, the type system used in an Object-Oriented language pke Python contains non-scalar types. However, data types in most of the database products such as Oracle, MySQL, etc., are of primitive types such as integers and strings.

In an ORM system, each class maps to a table in the underlying database. Instead of writing tedious database interfacing code yourself, an ORM takes care of these issues for you while you can focus on programming the logics of the system.

In order to use SQLAlchemy, we need to first install the pbrary using the PIP installer.

pip install sqlalchemy

SQLAlchemy is designed to operate with a DBAPI implementation built for a particular database. It uses dialect system to communicate with various types of DBAPI implementations and databases. All dialects require that an appropriate DBAPI driver is installed.

The following are the dialects included −

Firebird

Microsoft SQL Server

MySQL

Oracle

PostgreSQL

SQLite

Sybase

Since we are going to use SQLite database, we need to create a database engine for our database called test.db. Import create_engine() function from sqlalchemy module.

from sqlalchemy import create_engine
from sqlalchemy.dialects.sqpte import *
SQLALCHEMY_DATABASE_URL = "sqpte:///./test.db"
engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args = {"check_same_thread": False})

In order to interact with the database, we need to obtain its handle. A session object is the handle to database. Session class is defined using sessionmaker() − a configurable session factory method which is bound to the engine object.

from sqlalchemy.orm import sessionmaker, Session
session = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Next, we need a declarative base class that stores a catalog of classes and mapped tables in the Declarative system.

from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()

Books, a subclass of Base, is mapped to a book table in the database. Attributes in the Books class correspond to the data types of the columns in the target table. Note that the id attribute corresponds to the primary key in the book table.

from sqlalchemy import Column, Integer, String
class Books(Base):
   __tablename__ =  book 
   id = Column(Integer, primary_key=True, nullable=False)
   title = Column(String(50), unique=True)
   author = Column(String(50))
   pubpsher = Column(String(50))
   Base.metadata.create_all(bind=engine)

The create_all() method creates the corresponding tables in the database.

We now have to declare a Pydantic model that corresponds to the declarative base subclass (Books class defined above).

from typing import List
from pydantic import BaseModel, constr
class Book(BaseModel):
   id: int
   title: str
   author:str
   pubpsher: str
   class Config:
      orm_mode = True

Note the use of orm_mode=True in the config class indicating that it is mapped with the ORM class of SQLAlchemy.

Rest of the code is just similar to in-memory CRUD operations, with the difference being the operation functions interact with the database through SQLalchemy interface. The POST operation on the FastAPI apppcation object is defined below −

from fastapi import FastAPI, Depends
app=FastAPI()
def get_db():
   db = session()
   try:
      yield db
   finally:
   db.close()
@app.post( /add_new , response_model=Book)
def add_book(b1: Book, db: Session = Depends(get_db)):
   bk=Books(id=b1.id, title=b1.title, author=b1.author,
pubpsher=b1.pubpsher)
   db.add(bk)
   db.commit()
   db.refresh(bk)
   return Books(**b1.dict())

A database session is first estabpshed. Data from the POST request body is added to the book table as a new row. Execute the add_book() operation function to add sample data to the books table. To verify, you can use SQLiteStudio, a GUI tool for SQLite databases.

Two operation functions for GET operation are defined, one for fetching all the records, and one for the record matching a path parameter.

Following is the get_books() function bound to the /pst route. When executed, its server response is the pst of all records.

@app.get( /pst , response_model=List[Book])
def get_books(db: Session = Depends(get_db)):
   recs = db.query(Books).all()
   return recs

The /book/{id} route calls the get_book() function with id as path parameter. The SQLAlchemy’s query returns an object corresponding to the given id.

@app.get( /book/{id} , response_model=Book)
def get_book(id:int, db: Session = Depends(get_db)):
   return db.query(Books).filter(Books.id == id).first()

The following image shows the result of get_books() function executed from the Swagger UI.

The update and delete operations are performed by update_book() function (executed when /update/{id} route is visited) and del_book() function called when the route /delete/{id} is given in as the URL.

@app.put( /update/{id} , response_model=Book)
def update_book(id:int, book:Book, db: Session = Depends(get_db)):
   b1 = db.query(Books).filter(Books.id == id).first()
   b1.id=book.id
   b1.title=book.title
   b1.author=book.author
   b1.pubpsher=book.pubpsher
   db.commit()
   return db.query(Books).filter(Books.id == id).first()
@app.delete( /delete/{id} )
def del_book(id:int, db: Session = Depends(get_db)):
   try:
      db.query(Books).filter(Books.id == id).delete()
      db.commit()
   except Exception as e:
      raise Exception(e)
   return {"delete status": "success"}

If you intend to use any other database in place of SQLite, you need to only the change the dialect definition accordingly. For example, to use MySQL database and pymysql driver, change the statement of engine object to the following −

engine = create_engine( mysql+pymysql://user:password@localhost/test )

FastAPI - Using MongoDB

FastAPI can also use NoSQL databases such as MongoDB, Cassandra, CouchDB, etc. as the backend for the CRUD operations of a REST app. In this topic, we shall see how to use MongoDB in a FastAPI apppcation.

MongoDB is a document oriented database, in which the semi-structured documents are stored in formats pke JSON. Documents can contain many different key-value pairs, or key-array pairs, or even nested documents. It is a collection of key-value pairs, similar to Python dictionary object. One or more such documents are stored in a Collection.

A Collection in MongoDB is equivalent to a table in relational database. However, MongoDB (as do all the NoSQL databases) doesn t have a predefined schema. A Document is similar to single row in a table of SQL based relational database. Each document may be of variable number of key-value pairs. Thus MongoDB is a schema-less database.

To use MongoDB with FastAPI, MongoDB server must be installed on the machine. We also need to install PyMongo, an official Python driver for MongoDB.

pip3 install pymongo

Before interacting with MongoDB database through Python and FastAPI code, ensure that MongoDB is running by issuing following command (assuming that MongoDB server is installed in e:mongodb folder).

E:mongodbin>mongod
..
waiting for connections on port 27017

An object of MongoCpent class in the PyMongo module is the handle using which Python interacts with MongoDB server.

from pymongo import MongoCpent
cpent=MongoCpent()

We define Book as the BaseModel class to populate the request body (same as the one used in the SQLite example)

from pydantic import BaseModel
from typing import List
class Book(BaseModel):
   bookID: int
   title: str
   author:str
   pubpsher: str

Set up the FastAPI apppcation object −

from fastapi import FastAPI, status
app = FastAPI()

The POST operation decorator has "/add_new" as URL route and executes add_book() function. It parses the Book BaseModel object into a dictionary and adds a document in the BOOK_COLLECTION of test database.

@app.post("/add_new", status_code=status.HTTP_201_CREATED)
def add_book(b1: Book):
   """Post a new message to the specified channel."""
   with MongoCpent() as cpent:
      book_collection = cpent[DB][BOOK_COLLECTION]
      result = book_collection.insert_one(b1.dict())
      ack = result.acknowledged
      return {"insertion": ack}

Add a few documents using the web interface of Swagger UI by visiting http://localhost:8000/docs. You can verify the collection in the Compass GUI front end for MongoDB.

To retrieve the pst of all books, let us include the following get operation function − get_books(). It will be executed when "/books" URL route is visited.

@app.get("/books", response_model=List[str])
def get_books():
   """Get all books in pst form."""
   with MongoCpent() as cpent:
      book_collection = cpent[DB][BOOK_COLLECTION]
      bookpst = book_collection.distinct("title")
      return bookpst

In this case, the server response will be the pst of all titles in the books collection.

[
   "Computer Fundamentals",
   "Python Cookbook",
   "Let Us Python"
]

This following GET decorator retrieves a book document corresponding to given ID as path parameter −

@app.get("/books/{id}", response_model=Book)
def get_book(id: int):
   """Get all messages for the specified channel."""
   with MongoCpent() as cpent:
      book_collection = cpent[DB][BOOK_COLLECTION]
      b1 = book_collection.find_one({"bookID": id})
      return b1

Swagger UI documentation page shows the following interface −

The server’s JSON response, when the above function is executed, is as follows −

FastAPI - Using GraphQL

Facebook developed GraphQL in 2012, a new API standard with the intention of optimizing RESTful API Calls. GraphQL is the data query and manipulation language for the API. GraphQL is more flexible, efficient, and accurate as compared to REST. A GraphQL server provides only a single endpoint and responds with the precise data required by the cpent.

As GraphQL is compatible with ASGI, it can be easily integrated with a FastAPI apppcation. There are many Python pbraries for GraphQL. Some of them are psted below −

Strawberry

Ariadne

Tartiflette

Graphene

FastAPI’s official documentation recommends using Strawberry pbrary as its design is also based on type annotations (as in the case of FastAPI itself).

In order to integrate GraphQL with a FastAPI app, first decorate a Python class as Strawberry type.

@strawberry.type
class Book:
   title: str
   author: str
   price: int

Next, declare a Query class containing a function that returns a Book object.

@strawberry.type
class Query:
   @strawberry.field
   def book(self) -> Book:
   return Book(title="Computer Fundamentals", author="Sinha", price=300)

Use this Query class as the parameter to obtain Strawberry.Schema object

schema = strawberry.Schema(query=Query)

Then declare the objects of both GraphQL class and FastAPI apppcation class.

graphql_app = GraphQL(schema)
app = FastAPI()

Finally, add routes to the FastAPI object and run the server.

app.add_route("/book", graphql_app)
app.add_websocket_route("/book", graphql_app)

Visit http://localhost:8000/book in the browser. An in-browser GraphQL IDE opens up.

Below the commented section, enter the following query using the Explorer bar of the Graphiql IDE. Run the query to display the result in the output pane.

FastAPI - Websockets

A WebSocket is a persistent connection between a cpent and server to provide bidirectional, full-duplex communication between the two. The communication takes place over HTTP through a single TCP/IP socket connection. It can be seen as an upgrade of HTTP instead of a protocol itself.

One of the pmitations of HTTP is that it is a strictly half-duplex or unidirectional protocol. With WebSockets, on the other hand, we can send message-based data, similar to UDP, but with the repabipty of TCP. WebSocket uses HTTP as the initial transport mechanism, but keeps the TCP connection apve the connection after the HTTP response is received. Same connection object it can be used two-way communication between cpent and server. Thus, real-time apppcations can be built using WebSocket APIs.

FastAPI supports WebSockets through WebSocket class in FastAPI module. Following example demonstrates functioning of WebSocket in FastAPI apppcation.

First we have an index() function that renders a template (socket.html). It is bound to "/" route. The HTML file socket.html is placed in the “templates” folder.

main.py

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
templates = Jinja2Templates(directory="templates")
from fastapi.staticfiles import StaticFiles
app = FastAPI()
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/", response_class=HTMLResponse)
async def index(request: Request):
   return templates.TemplateResponse("socket.html", {"request": request})

The template file renders a text box and a button.

socket.html

<!DOCTYPE html>
<html>
   <head>
      <title>Chat</title>
      <script src="{{ url_for( static , path= ws.js ) }}"></script>
   </head>
   <body>
      <h1>WebSocket Chat</h1>
      <form action="" onsubmit="sendMessage(event)">
      <input type="text" id="messageText" autocomplete="off"/>
      <button>Send</button>
      </form>
      <ul id= messages >
      </ul>
   </body>
</html>

Inside the socket.html, there is a call to the JavaScript function to be executed on the form’s submit. Hence, to serve JavaScript, the "static" folder is first mounted. The JavaScript file ws.js is placed in the "static" folder.

ws.js

var ws = new WebSocket("ws://localhost:8000/ws");
ws.onmessage = function(event) {
   var messages = document.getElementById( messages )
   var message = document.createElement( p )
   var content = document.createTextNode(event.data)
   message.appendChild(content)
   messages.appendChild(message)
};
function sendMessage(event) {
   var input = document.getElementById("messageText")
   ws.send(input.value)
   input.value =   
   event.preventDefault()
}

As the JavaScript code is loaded, it creates a websocket pstening at "ws://localhost:8000/ws". The sendMessage() function directs the input message to the WebSocket URL.

This route invokes the websocket_endpoint() function in the apppcation code. The incoming connection request is accepted and the incoming message is echoed on the cpent browser. Add the below code to main.py.

from fastapi import WebSocket
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
   await websocket.accept()
   while True:
      data = await websocket.receive_text()
      await websocket.send_text(f"Message text was: {data}")

Save the FastAPI code file (main.py), template (socket.html) and JavaScript file (ws.js). Run the Uvicorn server and visit http://localhost:8000/ to render the chat window as below −

Type a certain text and press Send button. The input message will be redirected on the browser through the websocket.

FastAPI - FastAPI Event Handlers

Event handlers are the functions to be executed when a certain identified event occurs. In FastAPI, two such events are identified − startup and shutdown. FastAPI’s apppcation object has on_event() decorator that uses one of these events as an argument. The function registered with this decorator is fired when the corresponding event occurs.

The startup event occurs before the development server starts and the registered function is typically used to perform certain initiapzation tasks, estabpshing connection with the database etc. The event handler of shutdown event is called just before the apppcation shutdown.

Example

Here is a simple example of startup and shutdown event handlers. As the app starts, the starting time is echoed in the console log. Similarly, when the server is stopped by pressing ctrl+c, the shutdown time is also displayed.

main.py

from fastapi import FastAPI
import datetime
app = FastAPI()
@app.on_event("startup")
async def startup_event():
   print( Server started : , datetime.datetime.now())
@app.on_event("shutdown")
async def shutdown_event():
   print( server Shutdown : , datetime.datetime.now())

Output

It will produce the following output −

uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for apppcation startup.
Server started: 2021-11-23 23:51:45.907691
INFO: Apppcation startup complete.
INFO: Shutting down
INFO: Waiting for apppcation
server Shutdown: 2021-11-23 23:51:50.82955
INFO: Apppcation shutdown com
INFO: Finished server process

FastAPI - Mounting a Sub-App

If you have two independent FastAPI apps, one of them can be mounted on top of the other. The one that is mounted is called a sub-apppcation. The app.mount() method adds another completely "independent" apppcation in a specific path of the main app. It then takes care of handpng everything under that path, with the path operations declared in that sub-apppcation.

Let us first declare a simple FastAPI apppcation object to be used as a top level apppcation.

from fastapi import FastAPI
app = FastAPI()
@app.get("/app")
def mainindex():
   return {"message": "Hello World from Top level app"}

Then create another apppcation object subapp and add its own path operations.

subapp = FastAPI()
@subapp.get("/sub")
def subindex():
   return {"message": "Hello World from sub app"}

Mount this subapp object on the main app by using mount() method. Two parameters needed are the URL route and name of the sub apppcation.

app.mount("/subapp", subapp)

Both the main and sub apppcation will have its own docs as can be inspected using Swagger UI.

The sub apppcation’s docs are available at http://localhost:8000/subapp/docs

FastAPI - Middleware

A middleware is a function that is processed with every request (before being processed by any specific path operation) as well as with every response before returning it. This function takes each request that comes to your apppcation. It may perform some process with the request by running a code defined in it and then passes the request to be processed by the corresponding operation function. It can also process the response generated by the operation function before returning it.

Following are some of the middleware available in FastAPI pbrary −

CORSMiddleware

HTTPSRedirectMiddleware

TrustedHostMiddleware

GZipMiddleware

FastAPI provides app.add_middleware() function to handle server errors and custom exception handlers. In addition to the above integrated middleware, it is possible to define a custom middleware. The following example defines the addmiddleware() function and decorates it into a middleware by decorating it with @app.middleware() decorator

The function has two parameters, the HTTP request object, and the call_next() function that will send the API request to its corresponding path and return a response.

In addition to the middleware function, the apppcation also has two operation functions.

import time
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def addmiddleware(request: Request, call_next):
   print("Middleware works!")
   response = await call_next(request)
   return response
@app.get("/")
async def index():
   return {"message":"Hello World"}
@app.get("/{name}")
async def hello(name:str):
   return {"message":"Hello "+name}

As the apppcation runs, for each request made by the browser, the middleware output (Middleware works!) will appear in the console log before the response output.

FastAPI - Mounting Flask App

A WSGI apppcation written in Flask or Django framework can be wrapped in WSGIMiddleware and mounted it on a FastAPI app to make it ASGI comppant.

First install the Flask package in the current FastAPI environment.

pip3 install flask

The following code is a minimal Flask apppcation −

from flask import Flask
flask_app = Flask(__name__)
@flask_app.route("/")
def index_flask():
   return "Hello World from Flask!"

Then declare app as a FastAPI apppcation object and define an operation function for rendering Hello World message.

from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def index():
   return {"message": "Hello World from FastAPI!"}

Next, mount the flask apppcation as a sub apppcation of FastAPI main app using mount() method.

from fastapi.middleware.wsgi import WSGIMiddleware
app.mount("/flask", WSGIMiddleware(flask_app))

Run the Uvicorn development server.

uvicorn flaskapp:app –reload

The main FastAPI apppcation is available at the URL http://localhost:8000/ route.

{"message":"Hello World from FastAPI!"}

The Flask sub apppcation is mounted at the URL http://localhost:8000/flask.

Hello World from Flask!

FastAPI - Deployment

So far, we have been using a local development server "Uvicorn" to run our FastAPI apppcation. In order to make the apppcation pubpcly available, it must be deployed on a remote server with a static IP address. It can be deployed to different platforms such as Heroku, Google Cloud, nginx, etc. using either free plans or subscription based services.

In this chapter, we are going to use Deta cloud platform. Its free to use deployment service is very easy to use.

First of all, to use Deta, we need to create an account on its website with a suitable username and password of choice.

Once the account is created, install Deta CLI (command pne interface) on the local machine. Create a folder for your apppcation (c:fastapi_deta_app) If you are using Linux, use the following command in the terminal −

iwr https://get.deta.dev/cp.ps1 -useb | iex

If you are using Windows, run the following command from Windows PowerShell terminal −

PS C:fastapi_deta_app> iwr https://get.deta.dev/cp.ps1 -useb | iex
Deta was installed successfully to
C:UsersUser.detaindeta.exe
Run  deta --help  to get started

Use the login command and authenticate your username and password.

PS C:fastapi_deta_app> deta login
Please, log in from the web page. Waiting...
https://web.deta.sh/cp/60836
Logged in successfully.

In the same apppcation folder, create a minimal FastAPI apppcation in main.pyfile

# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
   return {"Hello": "World"}
@app.get("/items/{item_id}")
def read_item(item_id: int):
   return {"item_id": item_id}

Now we are ready to deploy our apppcation. Use deta new command from the power shell terminal.

PS C:fastapi_deta_app> deta new
Successfully created a new micro
{
   "name": "fastapi_deta_app",
   "id": "2b236e8f-da6a-409b-8d51-7c3952157d3c",
   "project": "c03xflte",
   "runtime": "python3.9",
   "endpoint": "https://vfrjgd.deta.dev",
   "region": "ap-southeast-1",
   "visor": "enabled",
   "http_auth": "disabled"
}
Adding dependencies...
…..
Instalpng collected packages: typing-extensions, pydantic, idna, sniffio, anyio, starlette, fastapi
Successfully installed anyio-3.4.0 fastapi-0.70.0 idna-3.3 pydantic-1.8.2 sniffio-1.2.0 starlette-0.16.0 typingextensions-4.0.0

Deta deploys the apppcation at the given endpoint (which may be randomly created for each apppcation). It first installs the required dependencies as if it is installed on the local machine. After successful deployment, open the browser and visit the URL as shown in front of endpoint key. The Swagger UI documentation can also be found at https://vfrigd.deta.dev/docs.