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:
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: Union[FastAPI, APIRouter], piccolo_crud: PiccoloCRUD, fastapi_kwargs: Optional[FastAPIKwargs] = None)[source]¶
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, butFastAPIWrapper
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 intoPiccoloCRUD
, for exampleready_only
andallow_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] = {})[source]¶
Allows kwargs to be passed into
FastAPIApp.add_api_route
.