FastAPI

https://fastapi.tiangolo.com/
Admin
FastAPI is a modern, high-performance web framework for building APIs with Python, known for its...
Tokens:821,639
Snippets:6,499
Trust Score:9
Update:2 days ago
Show doc for...
Tokens:
Raw
### Example beginning of redoc.standalone.js

Source: https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/

Expected start of the ReDoc JavaScript file when served correctly.

```javascript
/*! For license information please see redoc.standalone.js.LICENSE.txt */
!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
...
```

--------------------------------

### Install and run FastAPI CLI in development mode

Source: https://fastapi.tiangolo.com/fr/release-notes/

Upgrade FastAPI and start the development server with `fastapi dev main.py`. The command watches for changes and serves the app at http://127.0.0.1:8000 with API docs at /docs.

```shell
$ pip install --upgrade fastapi

$ fastapi dev main.py


 ╭────────── FastAPI CLI - Development mode ───────────╮
 │                                                     │
 │  Serving at: http://127.0.0.1:8000                  │
 │                                                     │
 │  API docs: http://127.0.0.1:8000/docs               │
 │                                                     │
 │  Running in development mode, for production use:   │
 │                                                     │
 │  fastapi run                                        │
 │                                                     │
 ╰─────────────────────────────────────────────────────╯

INFO:     Will watch for changes in these directories: ['/home/user/code/awesomeapp']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [2248755] using WatchFiles
INFO:     Started server process [2248757]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
```

--------------------------------

### Typical project structure for frontend serving

Source: https://fastapi.tiangolo.com/fr/reference/apirouter/

Example directory layout with app and dist folders.

```text
.
├── pyproject.toml
├── app
│   ├── __init__.py
│   └── main.py
└── dist
    ├── index.html
    └── assets
        └── app.js
```

--------------------------------

### APIRouter get method example

Source: https://fastapi.tiangolo.com/ru/reference/apirouter/

Example of using APIRouter.get to define a GET endpoint that returns a message. The router is included in the FastAPI app.

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

@router.get("/")
def read_root():
    return {"message": "Hello World"}

app.include_router(router)
```

--------------------------------

### Run fastapi dev with --entrypoint option

Source: https://fastapi.tiangolo.com/tutorial/first-steps/

Starts the development server by explicitly specifying the entrypoint main:app.

```shell
$ uv run fastapi dev --entrypoint main:app
```

--------------------------------

### @app.get

Source: https://fastapi.tiangolo.com/ja/reference/fastapi/

Add a path operation using an HTTP GET operation. The example shows a simple GET endpoint returning a list of items.

```APIDOC
## GET /

### Description
Add a path operation using an HTTP GET operation.

### Method
GET

### Endpoint
/items/

### Parameters

#### Path Parameters
- **path** (str) - Required - The URL path to be used for this path operation. For example, in `http://example.com/items`, the path is `/items`.

#### Query Parameters
- **response_model** (Any) - Optional - The type to use for the response. Default: `Default(None)`.
- **status_code** (int | None) - Optional - The default status code to be used for the response. Default: `None`.
- **tags** (list[str | Enum] | None) - Optional - A list of tags to be applied to the path operation. Default: `None`.
- **dependencies** (Sequence[Depends] | None) - Optional - A list of dependencies to be applied to the path operation. Default: `None`.
- **summary** (str | None) - Optional - A summary of the path operation. Default: `None`.
- **description** (str | None) - Optional - A description of the path operation. Default: `None`.
- **response_description** (str) - Optional - The description of the response. Default: `"Successful Response"`.
- **responses** (dict[int, dict] | None) - Optional - Additional responses to be shown in the OpenAPI schema. Default: `None`.
- **deprecated** (bool | None) - Optional - Mark the path operation as deprecated. Default: `None`.
- **operation_id** (str | None) - Optional - The operation ID to be used in the OpenAPI schema. Default: `None`.
- **response_model_include** (set | None) - Optional - Fields to include in the response model. Default: `None`.
- **response_model_exclude** (set | None) - Optional - Fields to exclude from the response model. Default: `None`.
- **response_model_by_alias** (bool) - Optional - Whether to use field aliases in the response model. Default: `True`.
- **response_model_exclude_unset** (bool) - Optional - Whether to exclude unset fields from the response model. Default: `False`.
- **response_model_exclude_defaults** (bool) - Optional - Whether to exclude fields with default values from the response model. Default: `False`.
- **response_model_exclude_none** (bool) - Optional - Whether to exclude fields with None values from the response model. Default: `False`.
- **include_in_schema** (bool) - Optional - Whether to include the path operation in the OpenAPI schema. Default: `True`.
- **response_class** (type[Response]) - Optional - The response class to use. Default: `Default(JSONResponse)`.
- **name** (str | None) - Optional - The name of the path operation. Default: `None`.
- **callbacks** (list[Callback] | None) - Optional - Callbacks for the path operation. Default: `None`.
- **openapi_extra** (dict | None) - Optional - Extra OpenAPI data for the path operation. Default: `None`.
- **generate_unique_id_function** (Callable) - Optional - Function to generate a unique ID for the path operation. Default: `Default(generate_unique_id)`.

### Request Example
```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]
```

### Response
#### Success Response (200)
- **list[dict]** - A list of items.

#### Response Example
```json
[
  {"name": "Empanada"},
  {"name": "Arepa"}
]
```
```

--------------------------------

### Define a GET endpoint with @app.get

Source: https://fastapi.tiangolo.com/fr/reference/fastapi/

Use the @app.get decorator to create a path operation for HTTP GET requests. The example returns a list of dictionaries from the /items/ path.

```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]
```

--------------------------------

### Example URL path

Source: https://fastapi.tiangolo.com/tutorial/first-steps/

Shows a full URL to illustrate what the path component is.

```text
https://example.com/items/foo
```

--------------------------------

### Define a GET path operation with APIRouter

Source: https://fastapi.tiangolo.com/fr/reference/apirouter/

Use this example to create a FastAPI router and add a GET endpoint using the @router.get decorator. The endpoint returns a list of dictionaries.

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

@router.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]
```

--------------------------------

### Start Traefik with Configuration File

Source: https://fastapi.tiangolo.com/advanced/behind-a-proxy/

Runs Traefik using the traefik.toml configuration file. The output shows that the configuration was loaded successfully.

```bash
$ ./traefik --configFile=traefik.toml

INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```

--------------------------------

### Importer module example

Source: https://fastapi.tiangolo.com/tutorial/debugging/

Example of another file that imports the app. When this file is run, the `if __name__ == "__main__"` block in `myapp.py` is not executed, so the server does not start.

```python
from myapp import app

# Some more code
```

--------------------------------

### Project structure with backend package

Source: https://fastapi.tiangolo.com/fastapi-cli/

Example directory layout where the app is inside a backend package. Use this structure to set the entrypoint accordingly.

```text
.
├── backend
│   ├── main.py
│   ├── __init__.py
```

--------------------------------

### Extracted path from URL

Source: https://fastapi.tiangolo.com/tutorial/first-steps/

The path portion of the example URL, starting from the first slash.

```text
/items/foo
```

--------------------------------

### Install FastAPI with uv add "fastapi[standard]"

Source: https://fastapi.tiangolo.com/

Run this command to add FastAPI with the standard extras to your project using uv. Keep "fastapi[standard]" in quotes so it works in all terminals.

```shell
$ uv add "fastapi[standard]"

---> 100%
```

--------------------------------

### Response with root_path from request scope

Source: https://fastapi.tiangolo.com/advanced/behind-a-proxy/

Example JSON response showing the root_path value when the server is started with --root-path /api/v1.

```json
{
    "message": "Hello World",
    "root_path": "/api/v1"
}
```

--------------------------------

### Initial project file structure

Source: https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/

Baseline directory layout before adding static files.

```text
.
├── app
│   ├── __init__.py
│   ├── main.py
```

--------------------------------

### Define startup event handler with @app.on_event("startup")

Source: https://fastapi.tiangolo.com/advanced/events/

Use this to run initialization logic before the application starts. The handler can be async or sync; the app won't accept requests until all startup handlers complete.

```python
from fastapi import FastAPI

app = FastAPI()

items = {}


@app.on_event("startup")
async def startup_event():
    items["foo"] = {"name": "Fighters"}
    items["bar"] = {"name": "Tenders"}


@app.get("/items/{item_id}")
async def read_items(item_id: str):
    return items[item_id]
```

--------------------------------

### Rendered relative URL with .path

Source: https://fastapi.tiangolo.com/advanced/templates/

Using the .path attribute, the link renders as a relative URL starting with /. For example, with id 42, it renders as this.

```html
<a href="/items/42">
```

--------------------------------

### Path operation decorator with path parameter

Source: https://fastapi.tiangolo.com/tutorial/bigger-applications/

Example showing that the path in the decorator must start with '/', so the router prefix must not end with '/'.

```python
@router.get("/{item_id}")
async def read_item(item_id: str): ...
```

--------------------------------

### Create a new FastAPI project with uv

Source: https://fastapi.tiangolo.com/tutorial/

Run these commands to initialize a bare Python project and add FastAPI with standard dependencies. The --bare flag creates only pyproject.toml, skipping sample files like main.py.

```shell
$ uv init awesome-project --bare
$ cd awesome-project
$ uv add "fastapi[standard]"

---> 100%
```

--------------------------------

### Define a path operation /items/ in FastAPI

Source: https://fastapi.tiangolo.com/advanced/behind-a-proxy/

Example FastAPI app with a GET endpoint at /items/ that returns a list. Used to illustrate redirect behavior when behind a proxy.

```python
from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
def read_items():
    return ["plumbus", "portal gun"]
```

--------------------------------

### Install httpx with uv add

Source: https://fastapi.tiangolo.com/tutorial/testing/

Required prerequisite before using TestClient. Run this command to add httpx to your project.

```shell
$ uv add httpx
```

--------------------------------

### Full FastAPI SQLModel CRUD application

Source: https://fastapi.tiangolo.com/tutorial/sql-databases/

Complete example of a FastAPI app with SQLModel for managing heroes, including model definitions, database setup, and CRUD endpoints.

```python
from fastapi import Depends, FastAPI, HTTPException, Query
from sqlmodel import Field, Session, SQLModel, create_engine, select


class HeroBase(SQLModel):
    name: str = Field(index=True)
    age: int | None = Field(default=None, index=True)


class Hero(HeroBase, table=True):
    id: int | None = Field(default=None, primary_key=True)
    secret_name: str


class HeroPublic(HeroBase):
    id: int


class HeroCreate(HeroBase):
    secret_name: str


class HeroUpdate(HeroBase):
    name: str | None = None
    age: int | None = None
    secret_name: str | None = None


sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

connect_args = {"check_same_thread": False}
engine = create_engine(sqlite_url, connect_args=connect_args)


def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


def get_session():
    with Session(engine) as session:
        yield session


app = FastAPI()


@app.on_event("startup")
def on_startup():
    create_db_and_tables()


@app.post("/heroes/", response_model=HeroPublic)
def create_hero(hero: HeroCreate, session: Session = Depends(get_session)):
    db_hero = Hero.model_validate(hero)
    session.add(db_hero)
    session.commit()
    session.refresh(db_hero)
    return db_hero


@app.get("/heroes/", response_model=list[HeroPublic])
def read_heroes(
    session: Session = Depends(get_session),
    offset: int = 0,
    limit: int = Query(default=100, le=100),
):
    heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
    return heroes


@app.get("/heroes/{hero_id}", response_model=HeroPublic)
def read_hero(hero_id: int, session: Session = Depends(get_session)):
    hero = session.get(Hero, hero_id)
    if not hero:
        raise HTTPException(status_code=404, detail="Hero not found")
    return hero


@app.patch("/heroes/{hero_id}", response_model=HeroPublic)
def update_hero(
    hero_id: int, hero: HeroUpdate, session: Session = Depends(get_session)
):
    hero_db = session.get(Hero, hero_id)
    if not hero_db:
        raise HTTPException(status_code=404, detail="Hero not found")
    hero_data = hero.model_dump(exclude_unset=True)
    hero_db.sqlmodel_update(hero_data)
    session.add(hero_db)
    session.commit()
    session.refresh(hero_db)
    return hero_db


@app.delete("/heroes/{hero_id}")
def delete_hero(hero_id: int, session: Session = Depends(get_session)):
    hero = session.get(Hero, hero_id)
    if not hero:
        raise HTTPException(status_code=404, detail="Hero not found")
    session.delete(hero)
    session.commit()
    return {"ok": True}
```

--------------------------------

### Using app.frontend to serve static files

Source: https://fastapi.tiangolo.com/fr/reference/fastapi/

Example of serving a frontend build from the 'dist' directory at the root path.

```python
from fastapi import FastAPI

app = FastAPI()
app.frontend("/", directory="dist")
```

--------------------------------

### Define a GET path operation with @app.get

Source: https://fastapi.tiangolo.com/fr/reference/fastapi/

Use the @app.get decorator to create a path operation that returns a list of items. The example shows a simple function returning a list of dictionaries.

```python
@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]
```

--------------------------------

### TrustedHostMiddleware의 __init__ 소스 코드

Source: https://fastapi.tiangolo.com/ko/reference/middleware/

TrustedHostMiddleware의 실제 구현 코드로, allowed_hosts의 유효성을 검사하고 속성을 설정합니다.

```python
def __init__(
    self,
    app: ASGIApp,
    allowed_hosts: Sequence[str] | None = None,
    www_redirect: bool = True,
) -> None:
    if allowed_hosts is None:
        allowed_hosts = ["*"]

    for pattern in allowed_hosts:
        assert "*" not in pattern[1:], ENFORCE_DOMAIN_WILDCARD
        if pattern.startswith("*") and pattern != "*":
            assert pattern.startswith("*."), ENFORCE_DOMAIN_WILDCARD
    self.app = app
    self.allowed_hosts = list(allowed_hosts)
    self.allow_any = "*" in allowed_hosts
    self.www_redirect = www_redirect
```

--------------------------------

### Import app from another module

Source: https://fastapi.tiangolo.com/tutorial/debugging/

Example of importing the FastAPI app from another file. In this case, the `if __name__ == "__main__"` block in `myapp.py` is not executed, so the server does not start automatically.

```python
from myapp import app
```

--------------------------------

### Python 3.10+ non-Annotated version with OAuth2 scopes

Source: https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/

Full example using non-Annotated type hints for Python 3.10+. Includes setup of OAuth2PasswordBearer with scopes, password hashing, and user models.

```python
from datetime import datetime, timedelta, timezone

import jwt
from fastapi import Depends, FastAPI, HTTPException, Security, status
from fastapi.security import (
    OAuth2PasswordBearer,
    OAuth2PasswordRequestForm,
    SecurityScopes,
)
from jwt.exceptions import InvalidTokenError
from pwdlib import PasswordHash
from pydantic import BaseModel, ValidationError

# to get a string like this run:
# openssl rand -hex 32
SECRET_KEY = "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30


fake_users_db = {
    "johndoe": {
        "username": "johndoe",
        "full_name": "John Doe",
        "email": "johndoe@example.com",
        "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc",
        "disabled": False,
    },
    "alice": {
        "username": "alice",
        "full_name": "Alice Chains",
        "email": "alicechains@example.com",
        "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$g2/AV1zwopqUntPKJavBFw$BwpRGDCyUHLvHICnwijyX8ROGoiUPwNKZ7915MeYfCE",
        "disabled": True,
    },
}


class Token(BaseModel):
    access_token: str
    token_type: str


class TokenData(BaseModel):
    username: str | None = None
    scopes: list[str] = []


class User(BaseModel):
    username: str
    email: str | None = None
    full_name: str | None = None
    disabled: bool | None = None


class UserInDB(User):
    hashed_password: str


password_hash = PasswordHash.recommended()

DUMMY_HASH = password_hash.hash("dummypassword")

oauth2_scheme = OAuth2PasswordBearer(
    tokenUrl="token",
    scopes={"me": "Read information about the current user.", "items": "Read items."},
)

app = FastAPI()


def verify_password(plain_password, hashed_password):
    return password_hash.verify(plain_password, hashed_password)


def get_password_hash(password):
    return password_hash.hash(password)
```

--------------------------------

### Create tables on startup with @app.on_event

Source: https://fastapi.tiangolo.com/tutorial/sql-databases/

Use this snippet to create database tables when the application starts. It calls create_db_and_tables() inside a startup event handler.

```python
# Code above omitted 👆

app = FastAPI()


@app.on_event("startup")
def on_startup():
    create_db_and_tables()

# Code below omitted 👇
```

--------------------------------

### Example URL with short=on

Source: https://fastapi.tiangolo.com/tutorial/query-params/

Example URL that sets the short query parameter to on, which FastAPI converts to True.

```http
http://127.0.0.1:8000/items/foo?short=on
```

--------------------------------

### Omit default value for required parameters

Source: https://fastapi.tiangolo.com/fr/release-notes/

Starting with FastAPI 0.78.0, you can omit the default value for required parameters, similar to Pydantic fields. This example shows the new syntax for `Path`, `Query`, `Cookie`, and `Header`.

```python
from fastapi import Cookie, FastAPI, Header, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
def main(
    item_id: int = Path(gt=0),
    query: str = Query(max_length=10),
    session: str = Cookie(min_length=3),
    x_trace: str = Header(title="Tracing header"),
):
    return {"message": "Hello World"}
```

--------------------------------

### Example file structure for a FastAPI application

Source: https://fastapi.tiangolo.com/tutorial/bigger-applications/

Shows a typical directory layout with app package, routers subpackage, and internal subpackage. Each directory contains an __init__.py file to make it a Python package.

```text
.
├── app
│   ├── __init__.py
│   ├── main.py
│   ├── dependencies.py
│   └── routers
│   │   ├── __init__.py
│   │   ├── items.py
│   │   └── users.py
│   └── internal
│       ├── __init__.py
│       └── admin.py
```

--------------------------------

### Install pydantic-settings with uv

Source: https://fastapi.tiangolo.com/advanced/settings/

Add the pydantic-settings package to your project using uv.

```bash
$ uv add pydantic-settings
---> 100%
```

--------------------------------

### Define lifespan with asynccontextmanager for startup and shutdown

Source: https://fastapi.tiangolo.com/advanced/events/

Use this async context manager to run code before the app starts (before yield) and after it finishes (after yield). The example simulates loading an ML model at startup and clearing it at shutdown.

```python
from contextlib import asynccontextmanager

from fastapi import FastAPI


def fake_answer_to_everything_ml_model(x: float):
    return x * 42


ml_models = {}


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load the ML model
    ml_models["answer_to_everything"] = fake_answer_to_everything_ml_model
    yield
    # Clean up the ML models and release the resources
    ml_models.clear()


app = FastAPI(lifespan=lifespan)


@app.get("/predict")
async def predict(x: float):
    result = ml_models["answer_to_everything"](x)
    return {"result": result}
```

--------------------------------

### Declare response model with return type annotation in FastAPI

Source: https://fastapi.tiangolo.com/tutorial/response-model/

Use a Pydantic model as the return type to validate and filter the response. The example defines a POST endpoint returning a single Item and a GET endpoint returning a list of Items.

```python
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.post("/items/")
async def create_item(item: Item) -> Item:
    return item


@app.get("/items/")
async def read_items() -> list[Item]:
    return [
        Item(name="Portal Gun", price=42.0),
        Item(name="Plumbus", price=32.0),
    ]
```

--------------------------------

### Run fastapi dev with file path

Source: https://fastapi.tiangolo.com/tutorial/first-steps/

Starts the development server by passing the file path main.py; FastAPI guesses the app object.

```shell
$ uv run fastapi dev main.py
```
Tokens:
Raw