Using pydantic models for GET request query params? Currently not possible, have to use dataclasses or normal classes.

[LasseGravesen]

Description

Is there a way to use pydantic models for GET requests? I would like to have a similar interface for both query params and for the body. So for instance, an example could look like this:

class PingArgs(BaseModel):
    """Model input for PingArgs."""

    dt: datetime.datetime = ...
    to_sum: List[int] = ...

    @validator("dt", pre=False, always=True, whole=True)
    def validate_dt(cls, v, values):
        """Validate dt."""
        parsed_dt = v.replace(tzinfo=None)
        return parsed_dt

@router.get("/ping", tags=["basic"])
def ping(args: PingArgs, request: Request):
    """Example."""
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "pong", "dt": args.dt.isoformat() "summed": sum(x for x in args.to_sum)},
    )

Where as, right now I think you would have to do something like this:

@router.get("/ping", tags=["basic"])
def ping(dt: datetime.datetime = Query(None), to_sum: List[int] = Query(None), request: Request):
    """Example."""
    parsed_dt = dt.replace(tzinfo=None)
    
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "pong", "dt": dt.isoformat() "summed": sum(x for x in to_sum)},
    )

Hope this can be clarified.

[tiangolo]

@LasseGravesen the problem is that GET operations don't have a body: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET

The Pydantic body you are defining in the first example is not equivalent to the query parameters in the second.

That Pydantic model would require a JSON body with something like:

{
  "dt": "2019-06-20T01:02:03+05:00",
  "to_sum": [2, 3, 4]
}

But what you can do, to avoid having to put all the parameters in each path operation, is to create a dependency, it would require the query parameters as you have them, and then you can put them in a Pydantic model with the shape you want, and it would return that Pydantic model.

Or even shorter, you can create a class dependency, check a very similar example in the docs: https://fastapi.tiangolo.com/tutorial/dependencies/classes-as-dependencies/

[LasseGravesen]

@tiangolo
It would not be a body, it would just be GET parameters as defined in a model. For instance, I come from the perspective of Flask and webargs, where you can define a 'model' and use that with the same interface for both GET and POST parameters, see for instance here:

https://github.com/marshmallow-code/webargs/blob/dev/examples/flask_example.py#L23-L34

That is not a body, but rather it puts the GET query parameters into a model.

I'll look into dependencies, but I hope you'll consider the above.

[LasseGravesen]

Dependencies might work, is there any reason why we couldn't use a pydantic class as a dependency?

[bs32g1038]

@LasseGravesen I think you may have misunderstood the get parameter.

why it not use a pydantic class as a dependency?

I think that:

• first of all, you must to know the query parameters are dynamic. for example:

http://www.localhost.com?q=1&page=1&pageSize=1&field='name'

Let's think about it. if use pydantic class, we should define the model. maybe like this:

class QueryArgs(BaseModel):
    q: int = ...
    page: int  = ...
    pageSize: int  = ... 
    field: string = ...

ok, all the parameters are defined in the model.

However, In practice, you will find that one request only need two field, such as page and pageSize,

Supposing the page range is 1-100, pageSize range is 1 - 100.

So if I request the pageSize is -1, it will throw error. however the “-1 ” represents no need for paging.

So I must remove the field from the model.

There are many more examples.

• More flexible and clarity. I can choice any field to check. because I only need to add field to the function as the params. you don't need to get the field from the object and can avoid the repeat the work.

---

To make a long story short, I think the code design style is better than use the pydantic model and more suitable for get parameters.

[Atheuz]

@tiangolo, I had an opportunity to fiddle a little bit more with this today.
Here is a full example of the different ways to specify parameters using depends: https://gist.github.com/Atheuz/075f4d8fe3b56d034741301ba2574ef1

You can run it using this command uvicorn run:app --reload --host 0.0.0.0 --port 8080

I essence: dataclass classes work if I specify Query(None) and Depends, pure classes work if I specify Query(None) and use Depends, and input parameters in the signature just works.

Pydantic classes do not work, at least in terms of the generated docs, it just says data instead of the expected dt and to_sum.

dataclasses in the generated docs:

pydantic in the generated docs:

[tiangolo]

Thanks for the help here guys!

@LasseGravesen a Pydantic model declares a JSON object, like a dict.

But for query parameters you need independent query parameters, each one with its own type.

Maybe an example can help to clarify it, imagine you have a POST endpoint that receives a body with a user, it contains a username and age. But the same endpoint also receives a query parameter demo that tells the API to only test if it would work, but not save the user.

How would you declare that demo in a model?

As part of the model for the user? ...then it would be required as part of the JSON body.
As another model? ...then it would be interpreted as a two-model composite body.

What if you had demo in a Pydantic model and then decided to add another query parameter token? How would FastAPI know that demo, inside a model, is a query parameter, but token, not in a model, is also a query parameter?

[LasseGravesen]

@tiangolo I would declare demo and token as a separate parameters for the endpoint, as they seem to me to be separate from the main request information(i.e. the user). In this case you could do either:

class UserPydantic(BaseModel):
    username: str = ...
    age: int = ...

@app.post("/api/v1/ping_pydantic", tags=["basic"])
def ping_pydantic(user: UserPydantic, demo: bool = Query(False), token: str = Query(None)):
    """Args defined in a pydantic model."""
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "pong", "user": user.dict()},
    )

If I really wanted to include the extra information in the "model", I would do it like this, which does not actually work right now, in that it just assumes everything is part of the body:

class UserPydantic2(BaseModel):
    username: str = ...
    age: int = ...
    demo: bool = Query(False)
    token: str = Query(None)

@app.post("/api/v1/ping_pydantic2", tags=["basic"])
def ping_pydantic2(user: UserPydantic2):
    """Args defined in a pydantic model."""
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "pong", "user": user.dict()},
    )

As an aside, you can actually do something like that with dataclasses, though it feels hacky because now the user model contains extra parameters that dont really belong to it.

@dataclass
class UserDataclass:
    username: str = Body(None)
    age: int = Body(None)
    demo: bool = Query(False)
    token: str = Query(None)

@app.post("/api/v1/user_dataclass", tags=["basic"])
def ping_dataclass(user: UserDataclass = Depends(UserDataclass)):
    """Args defined in a dataclass. Kinda broken."""
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "pong", "user": asdict(user)},
    )

You could also as you state use two separate models, one for the User and other for extra parameters, which actually works nicely if you use dataclasses, though you must use Depends.

@dataclass
class UserDataclass2:
    username: str = Body(None)
    age: int = Body(None)

@dataclass
class ExtraParams:
    demo: bool = Query(False)
    token: str = Query(None)

@app.post("/api/v1/user_dataclass2", tags=["basic"])
def ping_dataclass2(user: UserDataclass2 = Depends(UserDataclass2), extra_params: ExtraParams = Depends(ExtraParams)):
    """Args defined in two models."""
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "pong", "user": asdict(user)},
    )

But anyway, the use case I had was that I wanted a single way to define a lot of disparate arguments in a single model like webargs allows you to do, for all types of endpoints, i.e. the definition for body is defined in the same way as query params or url params. So the thought would be to have something like this:

@dataclass
class SearchArgs:
    query: str = Query(...)
    limit: int = Query(10)
    offset: int = Query(0)
    sort: str = Query("date")

@app.get("/api/v1/search_dataclass", tags=["basic"])
def search(args: SearchArgs = Depends(SearchArgs)):
    return JSONResponse(
        status_code=starlette.status.HTTP_200_OK,
        content={"detail": "search-result", "args": asdict(args), "results": {"abc": "def"}}
)

This doesnt work for a pydantic model, in that you just get data in the generated docs.

All this code can be found here: https://gist.github.com/LasseGravesen/8f5c2f510aa419592bf4fe4568db0ae2

[tiangolo]

@LasseGravesen You would do it like this:

from fastapi import FastAPI, Depends, Query

app = FastAPI()


class SearchArgs:
    def __init__(
        self,
        query: str = Query(...),
        limit: int = Query(10),
        offset: int = Query(0),
        sort: str = Query("date"),
    ):
        self.query = query
        self.limit = limit
        self.offset = offset
        self.sort = sort


@app.get("/api/v1/search_dataclass", tags=["basic"])
def search(args: SearchArgs = Depends()):
    return {"detail": "search-result", "args": args, "results": {"abc": "def"}}

Check the docs here: https://fastapi.tiangolo.com/tutorial/dependencies/classes-as-dependencies/

[LasseGravesen]

@tiangolo

Either of these work for me:

class SearchArgs1234:
    def __init__(
        self,
        query: str = Query(...),
        limit: int = Query(10),
        offset: int = Query(0),
        sort: str = Query("date"),
    ):
        self.query = query
        self.limit = limit
        self.offset = offset
        self.sort = sort


@app.get("/api/v1/search_class", tags=["basic"])
def search(args: SearchArgs1234 = Depends()):
    return {"detail": "search-result", "args": args, "results": {"abc": "def"}}


@dataclass
class SearchArgs123:
    query: str = Query(...)
    limit: int = Query(10)
    offset: int = Query(0)
    sort: int = Query("date")


@app.get("/api/v1/search_dataclass", tags=["basic"])
def search123(args: SearchArgs123 = Depends(SearchArgs123)):
    return {"detail": "search-result", "args": args, "results": {"abc": "def"}}

My preference would be to have pydantic as an option as well so I can be consistent with defining arguments with a single approach instead of mixing approaches, which I guess is my main point of contention now.

Thanks for leading me to Depends, it's good enough for now, though like I said my preference would be to have pydantic work as well for this use case also.

[zero0nee]

@LasseGravesen I was actually looking at the same use case. I get your point @tiangolo for why you might not what to use a pydantic model to define query parameters. However, for my use case, having that option would improve reusability a lot.

[btegs]

@tiangolo

I was setting up some GET and POST routes in FastAPI and I agree with the others here that the pydantic models for the next release of FastAPI should be expanded to include GET requests.

For a while I was wondering what was broken about the models I was creating and came across this thread. Any thoughts of adding this?

[Roukanken42]

With how tight integration of FastApi with Pydantic is, I too had expected to be able to use Pydantic models as query params using Depends().

Now I have duplicate code because of this:

@dataclass
class DatacenterNaturalKey:
    id: int = Path(..., description="Datacenter id of object")
    region: enums.Region = Path(
        ..., description="Region language code from which this object is"
    )
    patch: int = Path(..., description="Datacenter version number")


class DatacenterModel(Model):
    id: int = Schema(..., description="Datacenter id of object")
    region: enums.Region = Schema(
        ..., description="Region language code from which this object is"
    )
    patch: int = Schema(..., description="Datacenter version number")

    ... #rest of schema

Since Path is just an extension of Schema, I expected it to be able to declare NaturalKey as Pydantic model, and just extend it in DatacenterModel in addition to my base class Model and leave out these 3 fields. (which does work, but then I can't use NaturalKey as query params - which is the whole purpose of the class...)

[dmontagu]

@kuko0411 Instead of copying the code, you might be able to do:

DatacenterModel = DatacenterNaturalKey.__pydantic_model__

If you don't like what that does to your IDE/mypy, you can do something like:

if typing.TYPE_CHECKING:
    DatacenterModel = DatacenterNaturalKey
else:
    DatacenterModel = DatacenterNaturalKey.__pydantic_model__

(this isn't quite right, but it may be close enough to be useful.)

Given your design, I think this would require some extra massaging to get it to work exactly how you want, but it might be a useful starting point.

---

There is a relatively good reason for why this is hard to achieve with pydantic, and that is because FastAPI dependencies are built by reading the object signature. For a variety of reasons, Pydantic models don't have a signature that is compatible with fastapi dependencies. Even if we modified fastapi to handle pydantic models as a special case, it could still be hard to cover all edge cases due to things like the use of field aliases.

---

If someone really wants this, it shouldn't be too hard to start implementing as a PR -- take a look at get_typed_signature in https://github.com/tiangolo/fastapi/pull/451/files. You'd just need to add special handling for pydantic models based on the model.__fields__. I just don't know how hard it will be to handle all edge cases cleanly.

[jimcarreer]

This is an older issue but I wanted to show my solution to this problem:

class PagingQuery(BaseModel):
    page: conint(ge=1)
    page_size: conint(ge=1, le=250) = 50

    @classmethod
    async def depends(cls, page: int = 1, page_size: int = 50):
        try:
            return cls(page=page, page_size=page_size)
        except ValidationError as e:
            errors = e.errors()
            for error in errors:
                error['loc'] = ['query'] + list(error['loc'])
            raise HTTPException(422, detail=errors)


@app.get("/example", tags=["basic"])
def example(paging: PagingQuery = Depends(PagingQuery.depends)):
    return {"page": paging.page, "page_size": paging.page_size}

I don't know if this helps anyone / solves the problem but it does allow you to use pydantic validation for query parameters and get similar error responses to payload validation failure.

[myraygunbarrel]

Hi!
FastAPI + Pydantic present a really cool duo, but I couldn't find one (very natural, in my opinion) feature:
Is there a way to declare query parameters as Pydantic model with all advantages of validators and type checking? For example:

 class MyQueryParams(BaseModel):
    limit: int = Query(0, le=50, description='description')
    offset: int = Query(0, le=50)
    sort_by: str = Query(None, max_length=50)
    direction: str = Query(None, max_length=50)

    @validator('direction')
    def check_direction(cls, v):
        assert v in ('desc', 'asc'), 'wrong direction'
        return v

    @validator('sort_by')
    def check_sort_by(cls, v):
        assert v in ModelInDB.__fields__.keys(), 'must refer to DB-representation'
        return v

@router.get("/", response_model=MyResponse)
async def get_values(params: MyQueryParams = Depends(MyQueryParams)):
    pass

This solution doesn't work properly. What is the best practice to realize such case? In documents I've found only an example with ordinary python class without any custom validators.

[chinedu117]

"""
A decorator to parse query params into ppydantic model
"""

from typing import Type
from pydantic.main import BaseModel
from starlette.requests import Request

def as_query(cls: Type[BaseModel]):

    def as_query_func(request: Request):
        return cls(**request.query_params)

    setattr(cls,'as_query',as_query_func)
    return cls

"""
Add the decorator to the model
"""
@as_query
SampleModel(BaseModel):
    skip: int 
    limit: int

@router.get("/users")
def get_users(*,action=Depends(SampleModel.as_query)):
   pass

Hope this helps someone

[ghandic]

This should be looked at using the deepobject serialisation in openapi and supported just using Query out of the box - I've got another issue open on this that might be worth linking up

[silane]

I really want this feature, and implementing this feature leads to consistent behavior with Body.

FastAPI already has multiple body parameters feature using embed argument on Body.
For exmaple, sending body of

{
    "skip": 0,
    "limit": 30
}

to

@app.put("/")
async def test(skip: int = Body(..., embed=True), limit: int = Body(..., embed=True)):
    ...

will give you parameter skip to be 0 and limit to be 30.
And off course, we can receive the entire body like

class Filter(BaseModel):
     skip: int = None
     limit: int = None

@app.put("/")
async def test(filter: Filter = Body(..., embed=False)):
    ...

(Note on both cases, embed=True and embed=False can be omitted here because that's the default in each cases.)

The same way, we should add embed argument to Query.
Giving query ?skip=0&limit=30, we should be able to handle this both form of

@router.get("/")
def test(skip: int = Query(..., embed=True), limit: int = Query(..., embed=True)):
    pass

and

@router.get("/")
def test(filter: Filter = Query(..., embed=False)):
    pass

And to ensure backward compatibility, make embed=True be the default.

[ghandic]

In the meantime you can use https://github.com/ghandic/FastAPI-deepObject

[silane]

Why I want this is that, I want to declare time span with two query parameter start and end, and start must be earlier than end.
Pydantic can represent this constraint like this,

class Timespan(BaseModel):
    start: datetime
    end: datetime

    @root_validator
    def check_timespan(cls, values):
        if values.get('start') > values.get('end'):
            raise NegativeTimespanError(start_field="start", end_field="end") # My custom error
        return values

But currently, there is no way to use this pydantic model in query parameter.
Off course I can check this manually in the path operation function, but having a constraint in pydantic model gives better error details without effort when validation fails.

[chriswhite199]

@silane

You can get your model 'exploded' into query params easily enough:

@app.get("/")
def get_with_model_qparams(qparams: Timespan = Depends()):
   ...

and that will validate the individual query params as per their specific constraints. You'll also see them in the openapi spec as individual query params for the path (including constraint into) - at least in 0.71.0 where I am facing this issue

What you cannot currently do is root validators - in this case the error you raise will not be trapped inside fastapi.dependencies.utils.py::solve_dependencies, call to run_in_threadpool ~L527. and will instead be reported back to a normal client as a HTTP:500 error. The TestClient doesn't even see this, it just sees the errors raised when you invoke testclient.get("/") (rather than getting a response with status_code == 500).

So for the time being your only option might be to replace your root validator method with just a plain method that inspects 'self' and raises the NegativeTimespanError (for this you can add a handler or extend from HTTPError).

[chriswhite199]

An update on my above - raising HTTPException inside your root validator seems to work, but you'll need to craft you HTTPException(status_code=422, detail=...) detail field if you want it to match typical validation detail body

[silane]

@chriswhite199

I didn't know = Depends() do the trick! Thanks!
Is this behavior described in document? I could not find it.

I think raising HTTPException in root validator is odd because validator is part of pydantic model definition. Anyway thanks for your advise.

[chriswhite199]

@silane I think I worked from https://fastapi.tiangolo.com/tutorial/dependencies/classes-as-dependencies/ to get as far as using a single model to encapsulate multiple query params into a reusable model.

You're right about raising HTTPException, it doesn't seem right but that's the only way I could get it to work. I guess I could dig through the source again an try to submit a PR to address this + update the docs at the same time.

[silane]

Oh, I would really appreciate if you could do that!!

[jcwillox]

Just got this saucy snippet working, it's based on a previous comment but I got it working with way less boilerplate and it seems to work perfectly.

class QueryModel(BaseModel):
    def __init__(self, **kwargs):
        try:
            super().__init__(**kwargs)
        except ValidationError as e:
            errors = e.errors()
            for error in errors:
                error["loc"] = ("query",) + error["loc"]
            raise HTTPException(422, detail=errors)

# just inherit from QueryModel and use it like a normal pydantic model
class VideoQuery(QueryModel):
    project: ProjectType
    video: str

    @validator("video")
    def valid_video(cls, value: str) -> str:
        if value != "HelloWorld.mp4":
            raise ValueError("video does not exist")
        return value

@app.get("/videos/{video}")
def get_video(params: VideoQuery = Depends(VideoQuery)):
    pass

[Ledorub]

Strangely enough this doesn't work if a field has a hyphen-separated alias.

class Test(QueryModel):
    f: int = Field(alias='f-f')

In this case there is only one query param in the docs, named kwargs and server returns 422.

{"detail":[{"loc":["query","kwargs"],"msg":"field required","type":"value_error.missing"}]}

[jeffsawatzky]

@jcwillox instead of raising an HTTPException, would raising FastAPI's RequestValidationError be better? Then you can have your error handler handle the error and convert to an HTTPException in one place.

https://fastapi.tiangolo.com/tutorial/handling-errors/#requestvalidationerror-vs-validationerror

[jcwillox]

It's been a while since I've dealt with this issue, but if that works it sounds like it'd be the more correct option, perhaps there was some reason I didn't use it at the time or maybe I just didn't think about using it.

[ghandic]

Curious, how does it look in swagger?

[jcwillox]

Maybe somewhat surprisingly it works correctly AFAIK and shows the correct parameter names and types.

[Prerna-31]

I have tried most of the above solutions including class-dependencies, dataclass, overriding depends() and so on. All of them seem to be working fine but none of them meets my requirement. I want to validate query parameters and provide combined error messages to the user but it is not happening ion a particular scenario when errors get caught in pydantic(inbuilt) validation as well as manual/customised validation. For ex- Pydantic model or our dataclass expects user to provide id as integer and date in a specific format(YYYY0MM-DD). We have added manual validation method(@validator) to validate date but not for id and user by mistake provides an alphanumeric ID. In this scenario, I am able to show error only for id["Invalid id"] but not able to validate date because program execution stops immediately. I am wondering if there is a way to validate all the query parameters and provide a combined error messages("invalid id", "invalid date") to the client so that user can correct all of his inputs in one go?
Please help me in case anyone knows a way to achieve this.
Thanks!!

[jcwillox]

Sort of, with my method above FastAPI, will first perform pydantic validation on the types e.g. in my example it will ensure video is a string and project is ProjectType, it won't call any of the @validator methods.
If there are no failures at that stage then the QueryModel kicks in and performs full validation of the model, e.g. running the @validator method for video.
The QueryModel I demonstrated above will only return the first error, you could modify it to return multiple. Just make sure the initial type checking FastAPI does won't fail and you should be golden.