Query Parameter Models¶

If you have a group ofquery parameters that are related, you can create aPydantic model to declare them.

This would allow you tore-use the model inmultiple places and also to declare validations and metadata for all the parameters at once. 😎

Query Parameters with a Pydantic Model¶

Declare thequery parameters that you need in aPydantic model, and then declare the parameter asQuery:

fromtypingimportAnnotated,LiteralfromfastapiimportFastAPI,QueryfrompydanticimportBaseModel,Fieldapp=FastAPI()classFilterParams(BaseModel):limit:int=Field(100,gt=0,le=100)offset:int=Field(0,ge=0)order_by:Literal["created_at","updated_at"]="created_at"tags:list[str]=[]@app.get("/items/")asyncdefread_items(filter_query:Annotated[FilterParams,Query()]):returnfilter_query

fromtypingimportLiteralfromfastapiimportFastAPI,QueryfrompydanticimportBaseModel,Fieldapp=FastAPI()classFilterParams(BaseModel):limit:int=Field(100,gt=0,le=100)offset:int=Field(0,ge=0)order_by:Literal["created_at","updated_at"]="created_at"tags:list[str]=[]@app.get("/items/")asyncdefread_items(filter_query:FilterParams=Query()):returnfilter_query

FastAPI willextract the data foreach field from thequery parameters in the request and give you the Pydantic model you defined.

Check the Docs¶

You can see the query parameters in the docs UI at/docs:

Forbid Extra Query Parameters¶

In some special use cases (probably not very common), you might want torestrict the query parameters that you want to receive.

You can use Pydantic's model configuration toforbid anyextra fields:

fromtypingimportAnnotated,LiteralfromfastapiimportFastAPI,QueryfrompydanticimportBaseModel,Fieldapp=FastAPI()classFilterParams(BaseModel):model_config={"extra":"forbid"}limit:int=Field(100,gt=0,le=100)offset:int=Field(0,ge=0)order_by:Literal["created_at","updated_at"]="created_at"tags:list[str]=[]@app.get("/items/")asyncdefread_items(filter_query:Annotated[FilterParams,Query()]):returnfilter_query

fromtypingimportLiteralfromfastapiimportFastAPI,QueryfrompydanticimportBaseModel,Fieldapp=FastAPI()classFilterParams(BaseModel):model_config={"extra":"forbid"}limit:int=Field(100,gt=0,le=100)offset:int=Field(0,ge=0)order_by:Literal["created_at","updated_at"]="created_at"tags:list[str]=[]@app.get("/items/")asyncdefread_items(filter_query:FilterParams=Query()):returnfilter_query

If a client tries to send someextra data in thequery parameters, they will receive anerror response.

For example, if the client tries to send atool query parameter with a value ofplumbus, like:

https://example.com/items/?limit=10&tool=plumbus

They will receive anerror response telling them that the query parametertool is not allowed:

{"detail":[{"type":"extra_forbidden","loc":["query","tool"],"msg":"Extra inputs are not permitted","input":"plumbus"}]}

Summary¶

You can usePydantic models to declarequery parameters inFastAPI. 😎