FastAPI - basics

FastAPI¶

Python micro-framework 🐍 - fairly recent (2018)

occupies the same space as

• Flask - developed since 2010 - lightweight and extensible

• Django - developed since 2003 - perceived as more complete but also heavier

🚧 Micro-framework doesn’t mean not usable on large projects ⚠️

FastAPI vs Flask¶

FastAPI is similar on the surface to Flask, but much more modern!

• encourages a more structured approach

  • leverages type information (type annotations / Pydantic)

  • especially for automatic data validation / conversion

  • so you can define separate models for creation, reading, updating, etc.
    useful for example for password hashing (not exposed)

• in particular, automatically generates interactive documentation

• has native support for asynchronous programming

• as well as for websockets

Why FastAPI (and not something else)¶

1️⃣ You all more or less know how to do Python 🐍
so we eliminate everything that’s not Python-based

2️⃣ We’ll try to teach you things used elsewhere
And the FastAPI trend indeed seems to be experiencing spectacular growth!

Graphical User Interface¶

But actually... why are we interested in this?
The GUI (pronounce gooey) is what bridges 🌉 between:

GUI - two approaches¶

Old school
Using graphical libraries and developing a “thick” client

New age

Using the browser

FastAPI: we already know a bit¶

We already vaguely know how to use it, remember, we’ve already seen

Notice how simple it is to get started 😯
this is *a pro of Flask/FastAPI over Django (which requires a more advanced setup)

Quick recap¶

from fastapi import FastAPI

app = FastAPI()

Then we attach Python functions to URL paths
we call these functions route handlers or router functions

@app.get("/a/path/target")
def the_corresponding_function():
  // does very smart things
  return a_result    # which can be data (json) or html or whatever...

And to start the server?¶

fastapi dev my_app.py

fastapi dev my_app.py --port 8080

fastapi run my_app.py

# for example, here in dev mode on port 8080, where
# (*) my_app is the Python module name (so without .py; replace / with . if in a subfolder)
# (*) app is the name of the Python variable that refers to the FastAPI instance

uvicorn my_app:app --reload --port 8080

Parameters in a GET¶

For GET requests, we can write slightly more sophisticated URLs:

Of course then we need to retrieve the arguments in the handler function 🤔
FastAPI has it all figured out

@app.get("/some/route/data")
def get_parameters(
        name: str,
        age: int):
    return {'name': name, 'age': age}

Parametric URL¶

Now you can also - and more in line with best practices - define parameters within a URL itself
e.g. then your users would call URLs like /my/route/basile/42 instead

@app.get("/my/route/{name}/{age}")
def url_parameter(name: str, age: int):
    return ...

More kinds of parameters¶

in all generality, parameters can be passed in 5 different ways in an HTTP request:

1. in the URL path
   (e.g. /my/route/basile/42)

2. in the URL query string
   (e.g. /my/route?name=basile&age=42)

3. in the request body (e.g. for POST requests)

4. in the request headers

5. in cookies

here’s an example of a request with parameters in all these different places, freely inpired from the pixels-war game

Capturing parameters in the FastAPI route handler¶

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
from fastapi import FastAPI, Header, Cookie, Query, Body
from pydantic import BaseModel

app = FastAPI()

class PixelPayload(BaseModel):
    i: int
    j: int
    color: str  # e.g. "#ff0000"

@app.post("/api/{map}/set")
async def set_pixel(
    map: str,
    defer: bool = Query(False),
    authorization: str = Header(...),
    signature: str = Cookie(...),
    payload: PixelPayload = Body(...),
):
    ...

Returning data¶

1
2
3
4
@app.get("/my/route/{name}/{age}"):
def url_parameter(name: str, age: int):
    return {'name': name,
            'age': age}

{
  "name": "basile",
  "age": 42
}

→ A random generator (exercise)¶

• read the code - at least the 2 first get endpoints for now

• start the server

• point your browser at the documentation page at http://localhost:8000/docs

Exercise 1 - the docs¶

Exercise 2 - from the browser¶

Exercise 3 - from the terminal¶

Exercise 4 - error handling¶

Exercise solutions¶

1
http://localhost:8000/api/integer?min=100&max=200&count=10

1
2
3
4
5
6
from fastapi import HTTPException

def some_random_floats(min: float, max: float) -> float:
    if min >= max:
        raise HTTPException(status_code=400, detail="Invalid range")
    return random.uniform(min, max)

HTTP verbs¶

Quick reminder from the 1st episode, HTTP different possible requests

• GET: requests to obtain a resource from the server (html/css/js file, image, video, data, ...)

• POST: requests to send data to the server for processing (adding a user to a database, ...)

• PATCH: requests to partially modify a server resource (updating a user’s email address in the database)

• DELETE: requests to delete a server resource (deleting a comment on an article, ... )

These are the main types of requests but there are others, for the complete list you can check here: Hypertext Transfer Protocol

Parameters in a POST¶

however for POST, PATCH, DELETE requests, ...
the parameters are passed in the body of the request

Let’s look at an example

POST requests¶

And to start let’s look at what is sent by httpie when we do a POST

1
2
3
4
5
6
7
8
9
10
11
12
13
❯ http -v :8000/api/seed seed_value=42
POST /api/seed HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 18
Content-Type: application/json
Host: localhost:8000
User-Agent: HTTPie/3.2.4

{
    "seed_value": "42"
}

As we can see, the parameters are sent

• in JSON format

• and in the Body of the request - i.e. after the headers

→ On the FastAPI side¶

Here now is one FastAPI code that works well to handle this request

1
2
3
4
5
6
7
from fastapi import Body

@app.post("/api/seed")
# with Body() we indicate that the parameter comes from the request body
def set_seed(seed_value: int=Body(..., embed=True)):
    random.seed(seed_value)
    return {"message": f"Seed set to {seed_value}"}

What’s next¶

At this point you know how to implement FastAPI endpoints that handle GET and POST requests with parameters

We have many other things to see, including:

• how FastAPI leverages type annotations to do automatic validation

• how to return HTML rather than JSON data

• as well as a few other tips & tricks

We’ll see that in the following episodes...