Quickstart FastAPI

Quickstart (FastAPI)

• Applies to: FastAPI
• Best examples: examples/mini_fastapi_app.py, examples/demo_fastapi.py
• Related pages: Installation, Quickstart (Flask), Relationships and Includes

Status

The FastAPI adapter is currently experimental.

The repository already contains:

• a dedicated adapter under safrs/fastapi/
• a minimal example
• a fuller demo app
• FastAPI parity and error-handling tests

What the adapter gives you

The FastAPI adapter keeps SAFRS-style JSON:API CRUD and relationship semantics, while using FastAPI for:

• application wiring
• OpenAPI generation
• Swagger UI at /docs
• middleware and dependency patterns

Minimal app

Based on examples/mini_fastapi_app.py:

import safrs
from fastapi import FastAPI
from safrs import SAFRSBase
from safrs.fastapi.api import SafrsFastAPI
from sqlalchemy import Column, Integer, String, create_engine
from sqlalchemy.orm import declarative_base, scoped_session, sessionmaker

Base = declarative_base()


class User(SAFRSBase, Base):
    __tablename__ = "Users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String)


class _SAFRSDBWrapper:
    def __init__(self, session, model):
        self.session = session
        self.Model = model


def create_app() -> FastAPI:
    engine = create_engine("sqlite:///./mini_fastapi.db", future=True)
    SessionFactory = sessionmaker(bind=engine, autoflush=False, autocommit=False, future=True)
    Session = scoped_session(SessionFactory)

    safrs.DB = _SAFRSDBWrapper(Session, Base)
    Base.metadata.create_all(engine)

    app = FastAPI(title="SAFRS FastAPI mini app")

    @app.middleware("http")
    async def safrs_session_middleware(request, call_next):
        try:
            return await call_next(request)
        finally:
            Session.remove()

    api = SafrsFastAPI(app)
    api.expose_object(User)
    return app

The DB/session wrapper SAFRS expects

The FastAPI path does not use Flask-SQLAlchemy directly, so the example provides a tiny wrapper with:

• .session
• .Model

That is enough for SAFRS internals to work with the SQLAlchemy session and declarative base.

Session cleanup

The example uses FastAPI middleware to call Session.remove() after each request. Do not skip this part.

Docs endpoints

The minimal example exposes:

• /docs
• /openapi.json
• /swagger.json as a compatibility alias

Different example apps may choose a different canonical OpenAPI URL, but /docs is the main browser entry point.

Relationship item mode

The FastAPI adapter supports relationship_item_mode:

• disabled
• hidden
• enabled

This controls whether /{relationship}/{target_id} endpoints exist at runtime and whether they appear in the schema.

Method gating

FastAPI respects Model.http_methods. That affects both runtime behavior and generated OpenAPI operations.

Known differences from Flask

• Flask uses SAFRS Flask decorators and Flask-SQLAlchemy integration directly.
• FastAPI uses middleware and dependencies instead of Flask-only decorator patterns.
• Flask method_decorators are not supported by the FastAPI adapter; use FastAPI-native dependencies instead.
• FastAPI support is still explicitly experimental.

Where to go next

• examples/demo_fastapi.py
• Relationships and Includes
• Content Types and Errors