zhanymkanov/fastapi-best-practices
Snapshot of zhanymkanov/fastapi-best-practices: 17.8k★, Backend. FastAPI Best Practices and Conventions we used at our startup
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Snapshot
Top contributors
Show top contributors
FastAPI Best Practices
Opinionated list of best practices and conventions we use at our startups.
After several years of building production systems, we've made both good and bad decisions that significantly impacted our developer experience. Here are some lessons worth sharing.
Working with an AI agent? See AGENTS.md for the same rules in a terse, machine-readable format with a version matrix, Do/Don't blocks, and an anti-patterns checklist.
简体中文
Contents
- Project Structure
- Async Routes
- I/O Intensive Tasks
- CPU Intensive Tasks
- Pydantic
- Excessively use Pydantic
- Custom Base Model
- Decouple Pydantic BaseSettings
- Dependencies
- Beyond Dependency Injection
- Chain Dependencies
- Decouple & Reuse dependencies. Dependency calls are cached
- Prefer
asyncdependencies
- Miscellaneous
- Follow the REST
- FastAPI response serialization
- If you must use sync SDK, then run it in a thread pool.
- BackgroundTasks vs a real task queue
- ValueErrors might become Pydantic ValidationError
- Docs
- Set DB keys naming conventions
- Migrations. Alembic
- Set DB naming conventions
- SQL-first. Pydantic-second
- Set tests client async from day 0
- Use ruff
- Bonus Section
Project Structure
There are many ways to structure a project, but the best structure is one that is consistent, straightforward, and free of surprises.
Many example projects and tutorials organize projects by file type (e.g., crud, routers, models), which works well for microservices or smaller projects. However, this approach didn't scale well for our monolith with many domains and modules.
The structure I found more scalable and evolvable is inspired by Netflix's Dispatch, with some minor modifications.
fastapi-project
├── alembic/
├── src
│ ├── auth
│ │ ├── router.py
│ │ ├── schemas.py # pydantic models
│ │ ├── models.py # db models
│ │ ├── dependencies.py
│ │ ├── config.py # local configs
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ ├── service.py
│ │ └── utils.py
│ ├── aws
│ │ ├── client.py # client model for external service communication
│ │ ├── schemas.py
│ │ ├── config.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ └── utils.py
│ ├── posts
│ │ ├── router.py
│ │ ├── schemas.py
│ │ ├── models.py
│ │ ├── dependencies.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ ├── service.py
│ │ └── utils.py
│ ├── config.py # global configs
│ ├── models.py # global models
│ ├── exceptions.py # global exceptions
│ ├── pagination.py # global module e.g. pagination
│ ├── database.py # db connection related stuff
│ └── main.py
├── tests/
│ ├── auth
│ ├── aws
│ └── posts
├── templates/
│ └── index.html
├── requirements
│ ├── base.txt
│ ├── dev.txt
│ └── prod.txt
├── .env
├── .gitignore
├── logging.ini
└── alembic.ini
- Store all domain directories inside
srcfoldersrc/- highest level of an app, contains common models, configs, and constants, etc.src/main.py- root of the project, which inits the FastAPI app
- Each package has its own router, schemas, models, etc.
router.py- is a core of each module with all the endpointsschemas.py- for pydantic modelsmodels.py- for db modelsservice.py- module specific business logicdependencies.py- router dependenciesconstants.py- module specific constants and error codesconfig.py- e.g. env varsutils.py- non-business logic functions, e.g. response normalization, data enrichment, etc.exceptions.py- module specific exceptions, e.g.PostNotFound,InvalidUserData
- When package requires services or dependencies or constants from other packages - import them with an explicit module name
from src.auth import constants as auth_constants
from src.notifications import service as notification_service
from src.posts.constants import ErrorCode as PostsErrorCode # in case we have Standard ErrorCode in constants module of each package
Async Routes
FastAPI is an async-first framework—it's designed to work with async I/O operations, which is why it's so fast.
However, FastAPI doesn't restrict you to only async routes; you can use sync routes too. This might confuse beginners into thinking they're the same, but they're not.
I/O Intensive Tasks
Under the hood, FastAPI can effectively handle both async and sync I/O operations:
- FastAPI runs
syncroutes in a threadpool, so blocking I/O operations won't stop the event loop from executing other tasks. - If the route is defined as
async, it's called viaawaitand FastAPI trusts you to only perform non-blocking I/O operations.
The caveat is that if you violate that trust and execute blocking operations within async routes, the event loop won't be able to run other tasks until the blocking operation completes.
import asyncio
import time
from fastapi import APIRouter
router = APIRouter()
@router.get("/terrible-ping")
async def terrible_ping():
time.sleep(10) # I/O blocking operation for 10 seconds, the whole process will be blocked
return {"pong": True}
@router.get("/good-ping")
def good_ping():
time.sleep(10) # I/O blocking operation for 10 seconds, but in a separate thread for the whole `good_ping` route
return {"pong": True}
@router.get("/perfect-ping")
async def perfect_ping():
await asyncio.sleep(10) # non-blocking I/O operation
return {"pong": True}
What happens when we call:
GET /terrible-ping- FastAPI server receives a request and starts handling it
- Server's event loop and all queued tasks wait until
time.sleep()finishes- Since the route is
async, the server doesn't offload it to a threadpool—it blocks the entire event loop - Server won't accept any new requests while waiting
- Since the route is
- Server returns the response
- Only after responding does the server resume accepting new requests
GET /good-ping- FastAPI server receives a request and starts handling it
- FastAPI sends the entire
good_pingroute to the threadpool, where a worker thread runs the function - While
good_pingexecutes, the event loop continues processing other tasks (e.g., accepting new requests, calling the database)- The worker thread waits for
time.sleepto finish, independently of the main thread - The sync operation blocks only the worker thread, not the main event loop
- The worker thread waits for
- When
good_pingfinishes, the server returns a response to the client
GET /perfect-ping- FastAPI server receives a request and starts handling it
- FastAPI awaits
asyncio.sleep(10) - Event loop continues processing other tasks from the queue (e.g., accepting new requests, calling the database)
- When
asyncio.sleep(10)completes, the server finishes executing the route and returns a response to the client
[!WARNING] Notes on the thread pool:
- Threads require more resources than coroutines, so they are not as cheap as async I/O operations.
- Thread pool has a limited number of threads, i.e. you might run out of threads and your app will become slow. Read more (external link)
CPU Intensive Tasks
The second caveat is that non-blocking awaitables and threadpool offloading are only beneficial for I/O intensive tasks (e.g., file operations, database calls, external API requests).
- Awaiting CPU-intensive tasks (e.g., heavy calculations, data processing, video transcoding) provides no benefit since the CPU must actively work to complete them. In contrast, I/O operations are external—the server just waits for a response and can handle other tasks in the meantime.
- Running CPU-intensive tasks in other threads is also ineffective due to the GIL. In short, the GIL allows only one thread to execute Python bytecode at a time, making threads ineffective for CPU-bound work.
- To optimize CPU-intensive tasks, you should offload them to worker processes (e.g., using
multiprocessingor a task queue like Celery).
Related StackOverflow questions of confused users
- https://stackoverflow.com/questions/62976648/architecture-flask-vs-fastapi/70309597#70309597
- Here you can also check my answer
- https://stackoverflow.com/questions/65342833/fastapi-uploadfile-is-slow-compared-to-flask
- https://stackoverflow.com/questions/71516140/fastapi-runs-api-calls-in-serial-instead-of-parallel-fashion
Pydantic
Excessively use Pydantic
Pydantic has a rich set of features to validate and transform data.
In addition to standard features like required and optional fields with default values, Pydantic has built-in data processing tools like regex validation, enums, string manipulation, email validation, and more.
from enum import StrEnum
from pydantic import AnyUrl, BaseModel, EmailStr, Field
class MusicBand(StrEnum):
AEROSMITH = "AEROSMITH"
QUEEN = "QUEEN"
ACDC = "AC/DC"
class UserBase(BaseModel):
first_name: str = Field(min_length=1, max_length=128)
username: str = Field(min_length=1, max_length=128, pattern="^[A-Za-z0-9-_]+$")
email: EmailStr
age: int = Field(ge=18) # required, must be greater or equal to 18
favorite_band: MusicBand | None = None # only "AEROSMITH", "QUEEN", "AC/DC" values are allowed to be inputted
website: AnyUrl | None = None
Custom Base Model
Having a controllable global base model allows us to customize all the models within the app. For instance, we can enforce a standard datetime format or introduce a common method for all subclasses of the base model.
from datetime import datetime
from typing import Any
from zoneinfo import ZoneInfo
from fastapi.encoders import jsonable_encoder
from pydantic import BaseModel, ConfigDict, field_serializer
class CustomModel(BaseModel):
model_config = ConfigDict(populate_by_name=True)
@field_serializer("*", when_used="json", check_fields=False)
def _serialize_datetimes(self, value: Any) -> Any:
if isinstance(value, datetime):
if value.tzinfo is None:
value = value.replace(tzinfo=ZoneInfo("UTC"))
return value.strftime("%Y-%m-%dT%H:%M:%S%z")
return value
def serializable_dict(self, **kwargs):
"""Return a dict which contains only serializable fields."""
default_dict = self.model_dump()
return jsonable_encoder(default_dict)
In the example above, we have decided to create a global base model that:
- Serializes all datetime fields to a standard format with an explicit timezone
- Provides a method to return a dict with only serializable fields
Decouple Pydantic BaseSettings
BaseSettings is great for reading environment variables, but a single BaseSettings for the whole app gets messy. Split it across modules and domains.
# src.auth.config
from datetime import timedelta
from pydantic_settings import BaseSettings
class AuthConfig(BaseSettings):
JWT_ALG: str
JWT_SECRET: str
JWT_EXP: int = 5 # minutes
REFRESH_TOKEN_KEY: str
REFRESH_TOKEN_EXP: timedelta = timedelta(days=30)
SECURE_COOKIES: bool = True
auth_settings = AuthConfig()
# src.config
from pydantic import PostgresDsn, RedisDsn
from pydantic_settings import BaseSettings
from src.constants import Environment
class Config(BaseSettings):
DATABASE_URL: PostgresDsn
REDIS_URL: RedisDsn
SITE_DOMAIN: str = "myapp.com"
ENVIRONMENT: Environment = Environment.PRODUCTION
SENTRY_DSN: str | None = None
CORS_ORIGINS: list[str]
CORS_ORIGINS_REGEX: str | None = None
CORS_HEADERS: list[str]
APP_VERSION: str = "1.0"
settings = Config()
Dependencies
Beyond Dependency Injection
Pydantic is a great schema validator, but for complex validations that require database or external service calls, it's not enough.
FastAPI docs mostly present dependencies as DI for endpoints, but they're also great for request validation.
Dependencies can validate data against database constraints (e.g., checking if an email already exists, ensuring a user exists, etc.).
# dependencies.py
async def valid_post_id(post_id: UUID4) -> dict[str, Any]:
post = await service.get_by_id(post_id)
if not post:
raise PostNotFound()
return post
# router.py
@router.get("/posts/{post_id}", response_model=PostResponse)
async def get_post_by_id(post: dict[str, Any] = Depends(valid_post_id)):
return post
@router.put("/posts/{post_id}", response_model=PostResponse)
async def update_post(
update_data: PostUpdate,
post: dict[str, Any] = Depends(valid_post_id),
):
updated_post = await service.update(id=post["id"], data=update_data)
return updated_post
@router.get("/posts/{post_id}/reviews", response_model=list[ReviewsResponse])
async def get_post_reviews(post: dict[str, Any] = Depends(valid_post_id)):
post_reviews = await reviews_service.get_by_post_id(post["id"])
return post_reviews
If we didn't put data validation in a dependency, we would have to validate that post_id exists
in every endpoint and write the same tests for each of them.
Chain Dependencies
Dependencies can use other dependencies and avoid code repetition for similar logic.
# dependencies.py
from fastapi.security import OAuth2PasswordBearer
import jwt # PyJWT
from jwt.exceptions import InvalidTokenError
async def valid_post_id(post_id: UUID4) -> dict[str, Any]:
post = await service.get_by_id(post_id)
if not post:
raise PostNotFound()
return post
async def parse_jwt_data(
token: str = Depends(OAuth2PasswordBearer(tokenUrl="/auth/token"))
) -> dict[str, Any]:
try:
payload = jwt.decode(token, "JWT_SECRET", algorithms=["HS256"])
except InvalidTokenError:
raise InvalidCredentials()
return {"user_id": payload["id"]}
async def valid_owned_post(
post: dict[str, Any] = Depends(valid_post_id),
token_data: dict[str, Any] = Depends(parse_jwt_data),
) -> dict[str, Any]:
if post["creator_id"] != token_data["user_id"]:
raise UserNotOwner()
return post
# router.py
@router.get("/users/{user_id}/posts/{post_id}", response_model=PostResponse)
async def get_user_post(post: dict[str, Any] = Depends(valid_owned_post)):
return post
Decouple & Reuse dependencies. Dependency calls are cached
Dependencies can be reused multiple times, and they won't be recalculated - FastAPI caches dependency's result within a request's scope by default,
i.e. if valid_post_id gets called multiple times in one route, it will be called only once.
Knowing this, we can decouple dependencies onto multiple smaller functions that operate on a smaller domain and are easier to reuse in other routes.
For example, in the code below we are using parse_jwt_data three times:
valid_owned_postvalid_active_creatorget_user_post,
but parse_jwt_data is called only once, in the very first call.
# dependencies.py
from fastapi import BackgroundTasks
from fastapi.security import OAuth2PasswordBearer
import jwt # PyJWT
from jwt.exceptions import InvalidTokenError
async def valid_post_id(post_id: UUID4) -> Mapping:
post = await service.get_by_id(post_id)
if not post:
raise PostNotFound()
return post
async def parse_jwt_data(
token: str = Depends(OAuth2PasswordBearer(tokenUrl="/auth/token"))
) -> dict:
try:
payload = jwt.decode(token, "JWT_SECRET", algorithms=["HS256"])
except InvalidTokenError:
raise InvalidCredentials()
return {"user_id": payload["id"]}
async def valid_owned_post(
post: Mapping = Depends(valid_post_id),
token_data: dict = Depends(parse_jwt_data),
) -> Mapping:
if post["creator_id"] != token_data["user_id"]:
raise UserNotOwner()
return post
async def valid_active_creator(
token_data: dict = Depends(parse_jwt_data),
):
user = await users_service.get_by_id(token_data["user_id"])
if not user["is_active"]:
raise UserIsBanned()
if not user["is_creator"]:
raise UserNotCreator()
return user
# router.py
@router.get("/users/{user_id}/posts/{post_id}", response_model=PostResponse)
async def get_user_post(
worker: BackgroundTasks,
post: Mapping = Depends(valid_owned_post),
user: Mapping = Depends(valid_active_creator),
):
"""Get post that belong the active user."""
worker.add_task(notifications_service.send_email, user["id"])
return post
Prefer async dependencies
FastAPI supports both sync and async dependencies. It's tempting to use sync when you don't need to await anything, but that's not the best choice.
Just like routes, sync dependencies run in a threadpool. Threads have overhead that's unnecessary for small non-I/O operations.
See more (external link)
Miscellaneous
Follow the REST
Developing RESTful API makes it easier to reuse dependencies in routes like these:
GET /courses/:course_idGET /courses/:course_id/chapters/:chapter_id/lessonsGET /chapters/:chapter_id
The only caveat is having to use the same variable names in the path:
- If you have two endpoints
GET /profiles/:profile_idandGET /creators/:creator_idthat both validate whether the givenprofile_idexists, butGET /creators/:creator_idalso checks if the profile is creator, then it's better to renamecreator_idpath variable toprofile_idand chain those two dependencies.
# src.profiles.dependencies
async def valid_profile_id(profile_id: UUID4) -> Mapping:
profile = await service.get_by_id(profile_id)
if not profile:
raise ProfileNotFound()
return profile
# src.creators.dependencies
async def valid_creator_id(profile: Mapping = Depends(valid_profile_id)) -> Mapping:
if not profile["is_creator"]:
raise ProfileNotCreator()
return profile
# src.profiles.router.py
@router.get("/profiles/{profile_id}", response_model=ProfileResponse)
async def get_user_profile_by_id(profile: Mapping = Depends(valid_profile_id)):
"""Get profile by id."""
return profile
# src.creators.router.py
@router.get("/creators/{profile_id}", response_model=ProfileResponse)
async def get_user_profile_by_id(
creator_profile: Mapping = Depends(valid_creator_id)
):
"""Get creator's profile by id."""
return creator_profile
FastAPI response serialization
You might think you can return a Pydantic object that matches your route's response_model and skip some processing steps, but you'd be wrong.
FastAPI first converts the Pydantic object to a dict using jsonable_encoder, then validates the data against your response_model, and only then serializes it to JSON.
This means your Pydantic model object is created twice:
- First, when you explicitly create it to return from your route.
- Second, implicitly by FastAPI to validate the response data according to the response_model.
from fastapi import FastAPI
from pydantic import BaseModel, model_validator
app = FastAPI()
class ProfileResponse(BaseModel):
@model_validator(mode="after")
def debug_usage(self):
print("created pydantic model")
return self
@app.get("/", response_model=ProfileResponse)
async def root():
return ProfileResponse()
Logs Output:
[INFO] [2022-08-28 12:00:00.000000] created pydantic model
[INFO] [2022-08-28 12:00:00.000020] created pydantic model
If you must use sync SDK, then run it in a thread pool.
If you must use a library that's not async, run the HTTP calls in an external worker thread.
Use run_in_threadpool from Starlette.
from fastapi import FastAPI
from fastapi.concurrency import run_in_threadpool
from my_sync_library import SyncAPIClient
app = FastAPI()
@app.get("/")
async def call_my_sync_library():
my_data = await service.get_my_data()
client = SyncAPIClient()
await run_in_threadpool(client.make_request, data=my_data)
BackgroundTasks vs a real task queue
FastAPI's BackgroundTasks is convenient — and a footgun if you misuse it. Tasks run after the response is sent, in the same worker process. If the worker dies, the task is gone. There is no retry, no visibility, no scheduling.
Use BackgroundTasks when… | Use Celery / Arq / RQ when… |
|---|---|
| Task is short (< 1 second) | Task takes seconds to minutes |
| Failure can be silently dropped | You need retries or dead-letter handling |
| It's in-process (send email, log a row) | It's CPU-heavy or needs a separate worker pool |
| You don't need scheduling or rate limiting | You need cron, ETA, or rate limiting |
from fastapi import BackgroundTasks
@router.post("/signup")
async def signup(data: SignupIn, bg: BackgroundTasks):
user = await service.create_user(data)
bg.add_task(send_welcome_email, user.email) # fire-and-forget, in-process
return user
Rule of thumb: if you'd page someone when the task is lost, it doesn't belong in BackgroundTasks.
ValueErrors might become Pydantic ValidationError
If you raise a ValueError in a Pydantic schema that's used directly in a request body, FastAPI will return a detailed validation error response to users.
# src.profiles.schemas
from pydantic import BaseModel, field_validator
class ProfileCreate(BaseModel):
username: str
password: str
@field_validator("password", mode="after")
@classmethod
def valid_password(cls, password: str) -> str:
if not re.match(STRONG_PASSWORD_PATTERN, password):
raise ValueError(
"Password must contain at least "
"one lower character, "
"one upper character, "
"digit or "
"special symbol"
)
return password
# src.profiles.routes
from fastapi import APIRouter
router = APIRouter()
@router.post("/profiles")
async def create_profile(profile_data: ProfileCreate):
pass
Response Example:
Docs
- Unless your API is public, hide docs by default. Show it explicitly on the selected envs only.
from fastapi import FastAPI
from starlette.config import Config
config = Config(".env") # parse .env file for env variables
ENVIRONMENT = config("ENVIRONMENT") # get current env name
SHOW_DOCS_ENVIRONMENT = ("local", "staging") # explicit list of allowed envs
app_configs = {"title": "My Cool API"}
if ENVIRONMENT not in SHOW_DOCS_ENVIRONMENT:
app_configs["openapi_url"] = None # set url for docs as null
app = FastAPI(**app_configs)
- Help FastAPI to generate an easy-to-understand docs
- Set
response_model,status_code,description, etc. - If models and statuses vary, use
responsesroute attribute to add docs for different responses
- Set
from fastapi import APIRouter, status
router = APIRouter()
@router.post(
"/endpoints",
response_model=DefaultResponseModel, # default response pydantic model
status_code=status.HTTP_201_CREATED, # default status code
description="Description of the well documented endpoint",
tags=["Endpoint Category"],
summary="Summary of the Endpoint",
responses={
status.HTTP_200_OK: {
"model": OkResponse, # custom pydantic model for 200 response
"description": "Ok Response",
},
status.HTTP_201_CREATED: {
"model": CreatedResponse, # custom pydantic model for 201 response
"description": "Creates something from user request",
},
status.HTTP_202_ACCEPTED: {
"model": AcceptedResponse, # custom pydantic model for 202 response
"description": "Accepts request and handles it later",
},
},
)
async def documented_route():
pass
Will generate docs like this:
Set DB keys naming conventions
Explicitly setting the indexes' namings according to your database's convention is preferable over sqlalchemy's.
from sqlalchemy import MetaData
POSTGRES_INDEXES_NAMING_CONVENTION = {
"ix": "%(column_0_label)s_idx",
"uq": "%(table_name)s_%(column_0_name)s_key",
"ck": "%(table_name)s_%(constraint_name)s_check",
"fk": "%(table_name)s_%(column_0_name)s_fkey",
"pk": "%(table_name)s_pkey",
}
metadata = MetaData(naming_convention=POSTGRES_INDEXES_NAMING_CONVENTION)
Migrations. Alembic
- Migrations must be static and reversible. If your migrations depend on dynamically generated data, make sure only the data itself is dynamic, not its structure.
- Generate migrations with descriptive names and slugs. The slug is required and should explain the changes.
- Set a human-readable file template for new migrations. We use the
*date*_*slug*.pypattern, e.g.,2022-08-24_post_content_idx.py
# alembic.ini
file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(slug)s
Set DB naming conventions
Being consistent with names is important. Some rules we followed:
- lower_case_snake
- singular form (e.g.
post,post_like,user_playlist) - group similar tables with module prefix, e.g.
payment_account,payment_bill,post,post_like - stay consistent across tables, but concrete namings are ok, e.g.
- use
profile_idin all tables, but if some of them need only profiles that are creators, usecreator_id - use
post_idfor all abstract tables likepost_like,post_view, but use concrete naming in relevant modules likecourse_idinchapters.course_id
- use
_atsuffix for datetime_datesuffix for date
SQL-first. Pydantic-second
- Usually, database handles data processing much faster and cleaner than CPython will ever do.
- It's preferable to do all the complex joins and simple data manipulations with SQL.
- It's preferable to aggregate JSONs in DB for responses with nested objects.
For new projects, reach for SQLAlchemy 2.0's async API (AsyncSession, async_sessionmaker). The example below uses encode/databases for brevity — the SQL-first principle is what matters; the client is interchangeable.
# src.posts.service
from typing import Any
from pydantic import UUID4
from sqlalchemy import desc, func, select, text
from sqlalchemy.sql.functions import coalesce
from src.database import database, posts, profiles, post_review, products
async def get_posts(
creator_id: UUID4, *, limit: int = 10, offset: int = 0
) -> list[dict[str, Any]]:
select_query = (
select(
(
posts.c.id,
posts.c.slug,
posts.c.title,
func.json_build_object(
text("'id', profiles.id"),
text("'first_name', profiles.first_name"),
text("'last_name', profiles.last_name"),
text("'username', profiles.username"),
).label("creator"),
)
)
.select_from(posts.join(profiles, posts.c.owner_id == profiles.c.id))
.where(posts.c.owner_id == creator_id)
.limit(limit)
.offset(offset)
.group_by(
posts.c.id,
posts.c.type,
posts.c.slug,
posts.c.title,
profiles.c.id,
profiles.c.first_name,
profiles.c.last_name,
profiles.c.username,
profiles.c.avatar,
)
.order_by(
desc(coalesce(posts.c.updated_at, posts.c.published_at, posts.c.created_at))
)
)
return await database.fetch_all(select_query)
# src.posts.schemas
from typing import Any
from pydantic import BaseModel, UUID4
class Creator(BaseModel):
id: UUID4
first_name: str
last_name: str
username: str
class Post(BaseModel):
id: UUID4
slug: str
title: str
creator: Creator
# src.posts.router
from fastapi import APIRouter, Depends
router = APIRouter()
@router.get("/creators/{creator_id}/posts", response_model=list[Post])
async def get_creator_posts(creator: dict[str, Any] = Depends(valid_creator_id)):
posts = await service.get_posts(creator["id"])
return posts
Set tests client async from day 0
Writing integration tests with DB will likely lead to messed up event loop errors in the future.
Set the async test client immediately, using httpx with ASGITransport. Don't reach for async_asgi_testclient — it's unmaintained.
from typing import AsyncGenerator
import pytest
from httpx import AsyncClient, ASGITransport
from src.main import app # inited FastAPI app
@pytest.fixture
async def client() -> AsyncGenerator[AsyncClient, None]:
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
yield ac
@pytest.mark.asyncio
async def test_create_post(client: AsyncClient):
resp = await client.post("/posts")
assert resp.status_code == 201
Override dependencies in tests
Don't monkeypatch internals. FastAPI's dependency_overrides lets you swap any dependency for a test fake — auth, external clients, anything you don't want hitting the network.
from src.auth.dependencies import parse_jwt_data
from src.main import app
def fake_user():
return {"user_id": "00000000-0000-0000-0000-000000000001"}
@pytest.fixture(autouse=True)
def _override_auth():
app.dependency_overrides[parse_jwt_data] = fake_user
yield
app.dependency_overrides.clear()
Unless you have synchronous database connections (excuse me?) or don't plan to write integration tests.
Use ruff
With linters, you can forget about formatting the code and focus on writing the business logic.
Ruff is "blazingly-fast" new linter that replaces black, autoflake, isort, and supports more than 600 lint rules.
It's a popular good practice to use pre-commit hooks, but just using the script was ok for us.
#!/bin/sh -e
set -x
ruff check --fix src
ruff format src
Bonus Section
Some very kind people shared their own experience and best practices that are definitely worth reading. Check them out at issues section of the project.
For instance, lowercase00 has described in details their best practices working with permissions & auth, class-based services & views, task queues, custom response serializers, configuration with dynaconf, etc.
If you have something to share about your experience working with FastAPI, whether it's good or bad, you are very welcome to create a new issue. It is our pleasure to read it.
Related repositories
Node.js Best Practices, maintained at goldbergyoni/nodebestpractices, is a curated checklist of more than 80 recommendations for building Node.js applications, organized into eight categories from project architecture to Docker. Each entry combines a short recommendation with an explanation of the risk of skipping it and a link to a deeper write-up, rather than being a plain list of links.
Public APIs is a community-curated GitHub repository listing free, publicly accessible APIs across a wide range of categories, with auth type, HTTPS, and CORS noted for each entry. It's a browsable reference, not a library to install.
Awesome Python is a curated list maintained at vinta/awesome-python that groups Python frameworks, libraries, tools, and other resources into 14 categories, from AI & ML to Security and Other. The README calls it an opinionated guide rather than an exhaustive one, and points readers to a companion site, awesome-python.com, for searching and filtering entries instead of scrolling the raw file.
Awesome-Selfhosted is a community-maintained GitHub list at awesome-selfhosted/awesome-selfhosted that catalogs Free Software network-service and web-app projects meant for running on a server you control rather than someone else's cloud. Entries are grouped by category, each tagged with a license and a language or deployment option, and the project keeps proprietary alternatives on a separate Non-Free page.
Quick answers
How active is development on zhanymkanov/fastapi-best-practices?
The most recent commit recorded on zhanymkanov/fastapi-best-practices was 3 months ago, based on the GitHub push timestamp. The repository has 1.3k forks — one of the better signals of community interest.
How many stars does zhanymkanov/fastapi-best-practices have?
zhanymkanov/fastapi-best-practices has 17.8k GitHub stars — refresh the page for the live number, or check github.com/zhanymkanov/fastapi-best-practices. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What else is in the Backend space?
zhanymkanov/fastapi-best-practices is tracked by TopGit under the Backend category, alongside 2 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What language is zhanymkanov/fastapi-best-practices written in?
TopGit's last sync did not record a primary language for zhanymkanov/fastapi-best-practices. Open the repository on GitHub to see the full breakdown by file extension.
What topics is zhanymkanov/fastapi-best-practices associated with?
GitHub's repository topics for zhanymkanov/fastapi-best-practices: "best-practices", "fastapi". TopGit's editorial category is Backend.
Where do I read more about zhanymkanov/fastapi-best-practices?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/zhanymkanov/fastapi-best-practices is the definitive source.
Why is zhanymkanov/fastapi-best-practices categorized under Backend?
TopGit places zhanymkanov/fastapi-best-practices in the Backend category based on its GitHub topics and description (tagged: "best-practices", "fastapi"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Is fastapi-best-practices worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of fastapi-best-practices.