From Starlette / FastAPI#

Routing Decorators#

Litestar does not include any decorator as part of the Router or Litestar instances. Instead, all routes are declared using route handlers, either as standalone functions or controller methods. The handler can then be registered on an application or router instance.

from fastapi import FastAPI


app = FastAPI()


@app.get("/")
async def index() -> dict[str, str]: ...

from starlette.applications import Starlette
from starlette.routing import Route


async def index(request): ...


routes = [Route("/", endpoint=index)]

app = Starlette(routes=routes)

from litestar import Litestar, get


@get("/")
async def index() -> dict[str, str]: ...


app = Litestar([index])

See also

To learn more about registering routes, check out this chapter in the documentation:

Routers and Routes#

There are a few key differences between Litestar’s and Starlette’s Router class:

  1. The Litestar version is not an ASGI app

  2. The Litestar version does not include decorators: Use route handlers.

  3. The Litestar version does not support lifecycle hooks: Those have to be handled on the application layer. See lifecycle hooks

If you are using Starlette’s Routes, you will need to replace these with route handlers.

Host based routing#

Host based routing class is intentionally unsupported. If your application relies on Host you will have to separate the logic into different services and handle this part of request dispatching with a proxy server like nginx or traefik.

Dependency Injection#

The Litestar dependency injection system is different from the one used by FastAPI. You can read about it in the dependency injection section of the documentation.

In FastAPI you declare dependencies either as a list of functions passed to the Router or FastAPI instances, or as a default function argument value wrapped in an instance of the Depends class.

In Litestar dependencies are always declared using a dictionary with a string key and the value wrapped in an instance of the Provide class. This also allows to transparently override dependencies on every level of the application, and to easily access dependencies from higher levels.

from fastapi import FastAPI, Depends, APIRouter


async def route_dependency() -> bool: ...


async def nested_dependency() -> str: ...


async def router_dependency() -> int: ...


async def app_dependency(data: str = Depends(nested_dependency)) -> int: ...


router = APIRouter(dependencies=[Depends(router_dependency)])
app = FastAPI(dependencies=[Depends(nested_dependency)])
app.include_router(router)


@app.get("/")
async def handler(
    val_route: bool = Depends(route_dependency),
    val_router: int = Depends(router_dependency),
    val_nested: str = Depends(nested_dependency),
    val_app: int = Depends(app_dependency),
) -> None: ...

from litestar import Litestar, Provide, get, Router


async def route_dependency() -> bool: ...


async def nested_dependency() -> str: ...


async def router_dependency() -> int: ...


async def app_dependency(nested: str) -> int: ...


@get("/", dependencies={"val_route": Provide(route_dependency)})
async def handler(
    val_route: bool, val_router: int, val_nested: str, val_app: int
) -> None: ...


router = Router(dependencies={"val_router": Provide(router_dependency)})
app = Litestar(
    route_handlers=[handler],
    dependencies={
        "val_app": Provide(app_dependency),
        "val_nested": Provide(nested_dependency),
    },
)

See also

To learn more about dependency injection, check out this chapter in the documentation:

Lifespan#

If you’re using an async context manager and pass parameters to it, most likely the order of parameters is inversed between FastAPI and Litestar.

@asynccontextmanager
async def lifespan(
    _app: FastAPI,
    app_settings: AppSettings,
):
    # Setup code here
    yield
    # Teardown code here

@asynccontextmanager
async def lifespan(
    app_settings: AppSettings,
    _app: Litestar,
):
    # Setup code here
    yield
    # Teardown code here

Cookies#

While with FastAPI you usually set cookies on the response Response object, in Litestar there are two options: At the decorator level, using the response_cookies keyword argument, or dynamically at the response level (see: Setting Cookies dynamically)

@app.get("/")
async def index(response: Response) -> dict[str, str]:
    response.set_cookie(key="my_cookie", value="cookie_value")
    ...

@get(response_cookies={"my-cookie": "cookie-value"})
async def handler() -> str:
    ...

Dependencies parameters#

The way dependencies parameters are passed differs between FastAPI and Litestar, note the state: State parameter in the Litestar example. You can get the state either with the state kwarg in the handler or request.state (which point to the same object, a request local state, inherited from the application’s state), or via request.app.state, the application’s state.

from fastapi import Request

async def get_arqredis(request: Request) -> ArqRedis:
    return request.state.arqredis

from litestar import State

async def get_arqredis(state: State) -> ArqRedis:
    return state.arqredis

Post json#

In FastAPI, you pass the JSON object directly as a parameter to the endpoint, which will then be validated by Pydantic. In Litestar, you use the data keyword argument. The data will be parsed and validated by the associated modelling library.

class ObjectType(BaseModel):
    name: str

@app.post("/items/")
async def create_item(object_name: ObjectType) -> dict[str, str]:
    return {"name": object_name.name}

from litestar import post
from pydantic import BaseModel

class ObjectType(BaseModel):
    name: str

@post("/items/")
async def create_item(data: ObjectType) -> dict[str, str]:
    return {"name": data.name}

Default status codes#

Post defaults to 200 in FastApi and 201 in Litestar.

Templates#

In FastAPI, you use TemplateResponse to render templates. In Litestar, you use the Template class. Also FastAPI let you pass a dictionary while in Litestar you need to explicitly pass the context kwarg.

@app.get("/uploads")
async def get_uploads(request: Request):
    return templates.TemplateResponse(
        "uploads.html", {"request": request, "debug": app.state.debug}
    )

@get("/uploads")
async def get_uploads(app_settings) -> Template:
    return Template(
        name="uploads.html", context={"debug": app_settings.debug}
    )

Default handler names#

In FastAPI, the handler name defaults to the local name of the function. In Litestar, you need to explicitly declare the name parameter in the route decorator. This is important when using e.g. url_for.

@app.get("/blabla")
async def blabla() -> str:
    return "Blabla"

<a href="{{ url_for('blabla') }}">Blabla</a>

@get(path="/blabla", name="blabla")
async def blabla() -> str:
    return "Blabla"

<a href="{{ url_for('blabla') }}">Blabla</a>

Uploads#

In FastAPI, you use the File class to handle file uploads. In Litestar, you use the data keyword argument with Body and specify the media_type as RequestEncodingType.MULTI_PART. While this is more verbose, it’s also more explicit and communicates the intent more clearly.

@app.post("/upload/")
async def upload_file(files: list[UploadFile] = File(...)) -> dict[str, str]:
    return {"file_names": [file.filename for file in files]}

@post("/upload/")
async def upload_file(data: Annotated[list[UploadFile], Body(media_type=RequestEncodingType.MULTI_PART)]) -> dict[str, str]:
    return {"file_names": [file.filename for file in data]}

app = Litestar([upload_file])

Exceptions signature#

In FastAPI, status code and exception details can be passed to HTTPException as positional arguments, while in Litestar they are set with keywords arguments, e.g. status_code. Positional arguments to HTTPException in Litestar will be added to the exception detail. If migrating you just change your HTTPException import this will break.

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/")
async def index() -> None:
    response_fields = {"array": "value"}
    raise HTTPException(
        400, detail=f"can't get that field: {response_fields.get('array')}"
    )

from litestar import Litestar, get
from litestar.exceptions import HTTPException

@get("/")
async def index() -> None:
    response_fields = {"array": "value"}
    raise HTTPException(
        status_code=400, detail=f"can't get that field: {response_fields.get('array')}"
    )

app = Litestar([index])

Authentication#

FastAPI promotes a pattern of using dependency injection for authentication. You can do the same in Litestar, but the preferred way of handling this is extending Implementing Custom Authentication.

from fastapi import FastAPI, Depends, Request


async def authenticate(request: Request) -> None: ...


app = FastAPI()


@app.get("/", dependencies=[Depends(authenticate)])
async def index() -> dict[str, str]: ...

from litestar import get, ASGIConnection, BaseRouteHandler


async def authenticate(
    connection: ASGIConnection, route_handler: BaseRouteHandler
) -> None: ...


@get("/", guards=[authenticate])
async def index() -> dict[str, str]: ...

See also

To learn more about security and authentication, check out this chapter in the documentation:

Dependency overrides#

While FastAPI includes a mechanism to override dependencies on an existing application object, Litestar promotes architectural solutions to the issue this is aimed to solve. Therefore, overriding dependencies in Litestar is strictly supported at definition time, i.e. when you’re defining handlers, controllers, routers, and applications. Dependency overrides are fundamentally the same idea as mocking and should be approached with the same caution and used sparingly instead of being the default.

To achieve the same effect there are three general approaches:

  1. Structuring the application with different environments in mind. This could mean for example connecting to a different database depending on the environment, which in turn is set via and env-variable. This is sufficient and most cases and designing your application around this principle is a general good practice since it facilitates configurability and integration-testing capabilities

  2. Isolating tests for unit testing and using create_test_client

  3. Resort to mocking if none of the above approaches can be made to work

Middleware#

Pure ASGI middleware is fully compatible, and can be used with any ASGI framework. Middlewares that make use of FastAPI/Starlette specific middleware features such as Starlette’s BaseHTTPMiddleware are not compatible, but can be easily replaced by Creating Middlewares.