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:

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 AbstractAuthenticationMiddleware.

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.