FastAPI.

FastAPI is an async-first framework built for APIs, while Flask is a minimal synchronous framework that leaves most choices to you. FastAPI runs on the Asynchronous Server Gateway Interface (ASGI), the async standard between Python servers and apps. It reads your type hints to validate requests, serialize responses and generate API docs. Flask runs on the older Web Server Gateway Interface (WSGI), so each request holds a worker for its whole life, even in an async view.

Pick FastAPI for a new API that needs high concurrency, request validation and documentation without extra packages. Pick Flask when you want flexibility, simple server-rendered pages with its built-in Jinja templates, or its large set of mature extensions.

You register one function per method with the matching path operation decorator, such as @app.get or @app.post. FastAPI has a decorator for every HTTP method, including the less common @app.patch and @app.options. The same path can carry several methods, each handled by its own function, so /items/{item_id} below answers both PUT and DELETE.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def get_items():
    return {"method": "GET"}

@app.post("/items")
def create_item():
    return {"method": "POST"}

@app.put("/items/{item_id}")
def update_item(item_id: int):
    return {"method": "PUT", "item_id": item_id}

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"method": "DELETE", "item_id": item_id}

FastAPI matches a request on the path and the method together. A method with no function on a known path gets a 405 Method Not Allowed response without any code from you. Each decorator also adds that operation to the generated OpenAPI docs.

When one function must serve several methods, @app.api_route takes a methods list. Separate functions are usually better, because each handler stays small and easier to test.

You declare a Pydantic model and use it as the type of a path operation parameter, and FastAPI treats that parameter as the request body.

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False

@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

FastAPI reads the body as JSON, converts each field to its declared type and validates it. It then hands you an Item instance with editor completion on every field. If the data is invalid, FastAPI returns a 422 response before your function runs. Its detailed error messages name each bad field and say what was wrong.

FastAPI decides where each parameter comes from. A name that appears in the path is a path parameter. A single type such as int or str is a query parameter, and a Pydantic model is the body.

Fields with a default, such as is_offer, are optional in the JSON. The model also becomes a JSON Schema in the generated OpenAPI docs.

You set the default with the status_code parameter on the decorator, and you change it per request through a Response parameter.

from fastapi import FastAPI, status, Response

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item():
    return {"message": "Item created"}

@app.get("/items/{item_id}")
def get_item(item_id: int, response: Response):
    if item_id == 404:
        response.status_code = status.HTTP_404_NOT_FOUND
        return {"error": "Item not found"}
    return {"item_id": item_id}

The status_code on the decorator is what FastAPI returns when the function succeeds, and it also documents that code in the OpenAPI schema. The status module holds named constants such as status.HTTP_201_CREATED. They are the same numbers, but the names read better and your editor can complete them.

Declaring a Response parameter gives you a temporary response object. Set its status_code and FastAPI copies that code into the real response, while the returned data still goes through any response_model.

For errors, raising HTTPException with a status_code and a detail is the more common pattern, because it stops the function at once.

Pydantic is a data validation library that uses Python type hints to check and convert data. FastAPI integrates it through your type annotations. A BaseModel used as a parameter type becomes the request body, and one used as the response_model shapes the output. FastAPI then uses Pydantic for these jobs:

• It validates incoming request data and answers bad data with a 422.
• It serializes Python objects in responses to JSON.
• It generates the JSON Schema behind the API docs.
• It returns detailed validation error messages.

from pydantic import BaseModel, field_validator
from typing import Optional

class User(BaseModel):
    name: str
    email: str
    age: Optional[int] = None
    
    @field_validator('email')
    def validate_email(cls, v):
        if '@' not in v:
            raise ValueError('Invalid email')
        return v

A field validator adds a rule that type hints cannot express, like the email check above. Since FastAPI now requires Pydantic v2, use @field_validator instead of the older @validator.

You name the parameter in the path with braces, declare it in the function signature with a type hint, and add constraints with Path().

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def get_item(
    item_id: int = Path(..., gt=0, description="The ID of the item")
):
    return {"item_id": item_id}

@app.get("/users/{user_id}/items/{item_id}")
def get_user_item(user_id: int, item_id: int):
    return {"user_id": user_id, "item_id": item_id}

FastAPI converts the path segment to the declared type, so item_id arrives as an int, not a string. A value like /items/foo fails the conversion and gets a validation error before your code runs.

Path() adds numeric constraints such as gt for greater than and le for less than or equal. It also takes a description that appears in the docs. Here gt=0 rejects zero and negative IDs.

A route can hold several path parameters, as the second function shows. Routes are matched in declaration order, so /users/me must come before /users/{user_id}.

To allow only a fixed set of values, type the parameter with a class that subclasses str and Enum. Newer code often writes the gt=0 constraint as Annotated[int, Path(gt=0)].