FastAPI

FastAPI is a powerful ASGI web framework, built on top of Starlette, which lets you build an API very easily, with interactive docs.

It does this by making heavy use of type annotations.

By using FastAPIWrapper we can annotate our PiccoloCRUD endpoints so FastAPI can automatically document them for us. It’s an incredibly productive way of building an API.

We’re able to create all of these endpoints, and more, with very little code:

---

Example

In this example we’re building the API for a movie app. Assuming you have defined a Piccolo Table called Movie:

# app.py

from fastapi import FastAPI
from piccolo_api.fastapi.endpoints import FastAPIWrapper
from piccolo_api.crud.endpoints import PiccoloCRUD

from movies.tables import Movie


app = FastAPI()


FastAPIWrapper(
    root_url="/movie/",
    fastapi_app=app,
    piccolo_crud=PiccoloCRUD(
        table=Movie,
        read_only=False,
    )
)

We can now run this app using an ASGI server such as uvicorn.

uvicorn app:app

Then try out the following:

• OpenAPI docs: http://127.0.0.1:8000/docs/

• API endpoint: http://127.0.0.1:8000/movie/

To see full examples of FastAPI apps built this way, take a look at:

• PyMDb - a movie database.

• A headless blog.

---

Configuring the endpoints

If you want more control over the endpoints, you can do so using FastAPIKwargs, which allows you to specify additional arguments to pass into FastAPIApp.add_api_route.

Example

In the following example, we add tags to the endpoints, which separates them in the docs UI.

We also mark one of the endpoints as deprecated.

from fastapi import FastAPI
from piccolo_api.fastapi.endpoints import FastAPIWrapper, FastAPIKwargs
from piccolo_api.crud.endpoints import PiccoloCRUD

from my_app.tables import Movie


app = FastAPI()


FastAPIWrapper(
    root_url="/movie/",
    fastapi_app=app,
    piccolo_crud=PiccoloCRUD(
        table=Movie,
        read_only=False,
    ),
    fastapi_kwargs=FastAPIKwargs(
        all_routes={"tags": ["Movie"]},  # Added to all endpoints
        get={"deprecated": True},  # Just added to the 'get' endpoint
    )
)

---

Authentication

You can wrap your FastAPI app with any of our authentication middleware, such as SessionAuthMiddleware.

If you want to use FastAPI’s builtin OAuth2 features to protect some endpoints, you can do so as follows:

OAuth2 example

In the following example we pass dependencies into FastAPIKwargs to protect endpoints with unsafe HTTP methods.

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer
from piccolo_api.fastapi.endpoints import FastAPIWrapper, FastAPIKwargs
from piccolo_api.crud.endpoints import PiccoloCRUD

from my_app.tables import Movie

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")

FastAPIWrapper(
    root_url="/movie/",
    fastapi_app=app,
    piccolo_crud=PiccoloCRUD(
        table=Movie,
        read_only=False,
    ),
    fastapi_kwargs=FastAPIKwargs(
        all_routes={"tags": ["Movie"]},  # Added to all endpoints
        post={"dependencies": [Depends(oauth2_scheme)]}, # protected route
        put={"dependencies": [Depends(oauth2_scheme)]},  # protected route
        patch={"dependencies": [Depends(oauth2_scheme)]},  # protected route
        delete_single={"dependencies": [Depends(oauth2_scheme)]},  # protected route
    )
)

See this example project for more details.

---

Source

FastAPIWrapper

class piccolo_api.fastapi.endpoints.FastAPIWrapper(root_url: str, fastapi_app: FastAPI | APIRouter, piccolo_crud: PiccoloCRUD, fastapi_kwargs: FastAPIKwargs | None = None)

Wraps PiccoloCRUD so it can easily be integrated into FastAPI. PiccoloCRUD can be used with any ASGI framework, but this way you get some of the benefits of FastAPI - namely, the OpenAPI integration. You get more control by building your own endpoints by hand, but FastAPIWrapper works great for getting endpoints up and running very quickly, and reducing boilerplate code.

Parameters:

• root_url – The URL to mount the endpoint at - e.g. '/movies/'.

• fastapi_app – The FastAPI instance you want to attach the endpoints to.

• piccolo_crud – The PiccoloCRUD instance to wrap. FastAPIWrapper will obey the arguments passed into PiccoloCRUD, for example ready_only and allow_bulk_delete.

• fastapi_kwargs – Specifies the extra kwargs to pass to FastAPI’s add_api_route.

FastAPIKwargs

class piccolo_api.fastapi.endpoints.FastAPIKwargs(all_routes: Dict[str, Any] = {}, get: Dict[str, Any] = {}, delete: Dict[str, Any] = {}, post: Dict[str, Any] = {}, put: Dict[str, Any] = {}, patch: Dict[str, Any] = {}, get_single: Dict[str, Any] = {}, delete_single: Dict[str, Any] = {})

Allows kwargs to be passed into FastAPIApp.add_api_route.