Parámetros de Query¶

Cuando declaras otros parámetros de función que no son parte de los parámetros de path, son automáticamente interpretados como parámetros de "query".

fromfastapiimportFastAPIapp=FastAPI()fake_items_db=[{"item_name":"Foo"},{"item_name":"Bar"},{"item_name":"Baz"}]@app.get("/items/")asyncdefread_item(skip:int=0,limit:int=10):returnfake_items_db[skip:skip+limit]

La query es el conjunto de pares clave-valor que van después del? en una URL, separados por caracteres&.

Por ejemplo, en la URL:

http://127.0.0.1:8000/items/?skip=0&limit=10

...los parámetros de query son:

• skip: con un valor de0
• limit: con un valor de10

Como son parte de la URL, son "naturalmente" strings.

Pero cuando los declaras con tipos de Python (en el ejemplo anterior, comoint), son convertidos a ese tipo y validados respecto a él.

Todo el mismo proceso que se aplica para los parámetros de path también se aplica para los parámetros de query:

• Soporte del editor (obviamente)
• "parsing" de datos
• Validación de datos
• Documentación automática

Valores por defecto¶

Como los parámetros de query no son una parte fija de un path, pueden ser opcionales y pueden tener valores por defecto.

En el ejemplo anterior, tienen valores por defecto deskip=0 ylimit=10.

Entonces, ir a la URL:

http://127.0.0.1:8000/items/

sería lo mismo que ir a:

http://127.0.0.1:8000/items/?skip=0&limit=10

Pero si vas a, por ejemplo:

http://127.0.0.1:8000/items/?skip=20

Los valores de los parámetros en tu función serán:

• skip=20: porque lo configuraste en la URL
• limit=10: porque ese era el valor por defecto

Parámetros opcionales¶

De la misma manera, puedes declarar parámetros de query opcionales, estableciendo su valor por defecto enNone:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id:str,q:str|None=None):ifq:return{"item_id":item_id,"q":q}return{"item_id":item_id}

En este caso, el parámetro de funciónq será opcional y seráNone por defecto.

Conversión de tipos en parámetros de query¶

También puedes declarar tiposbool, y serán convertidos:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id:str,q:str|None=None,short:bool=False):item={"item_id":item_id}ifq:item.update({"q":q})ifnotshort:item.update({"description":"This is an amazing item that has a long description"})returnitem

En este caso, si vas a:

http://127.0.0.1:8000/items/foo?short=1

o

http://127.0.0.1:8000/items/foo?short=True

o

http://127.0.0.1:8000/items/foo?short=true

o

http://127.0.0.1:8000/items/foo?short=on

o

http://127.0.0.1:8000/items/foo?short=yes

o cualquier otra variación (mayúsculas, primera letra en mayúscula, etc.), tu función verá el parámetroshort con un valorbool deTrue. De lo contrario, seráFalse.

Múltiples parámetros de path y de query¶

Puedes declarar múltiples parámetros de path y de query al mismo tiempo,FastAPI sabe cuál es cuál.

Y no tienes que declararlos en un orden específico.

Serán detectados por nombre:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/users/{user_id}/items/{item_id}")asyncdefread_user_item(user_id:int,item_id:str,q:str|None=None,short:bool=False):item={"item_id":item_id,"owner_id":user_id}ifq:item.update({"q":q})ifnotshort:item.update({"description":"This is an amazing item that has a long description"})returnitem

Parámetros de query requeridos¶

Cuando declaras un valor por defecto para parámetros que no son de path (por ahora, solo hemos visto parámetros de query), entonces no es requerido.

Si no quieres agregar un valor específico pero solo hacer que sea opcional, establece el valor por defecto comoNone.

Pero cuando quieres hacer un parámetro de query requerido, simplemente no declares ningún valor por defecto:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_user_item(item_id:str,needy:str):item={"item_id":item_id,"needy":needy}returnitem

Aquí el parámetro de queryneedy es un parámetro de query requerido de tipostr.

Si abres en tu navegador una URL como:

http://127.0.0.1:8000/items/foo-item

...sin agregar el parámetro requeridoneedy, verás un error como:

{"detail":[{"type":"missing","loc":["query","needy"],"msg":"Field required","input":null}]}

Comoneedy es un parámetro requerido, necesitarías establecerlo en la URL:

http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

...esto funcionaría:

{"item_id":"foo-item","needy":"sooooneedy"}

Y por supuesto, puedes definir algunos parámetros como requeridos, algunos con un valor por defecto, y algunos enteramente opcionales:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_user_item(item_id:str,needy:str,skip:int=0,limit:int|None=None):item={"item_id":item_id,"needy":needy,"skip":skip,"limit":limit}returnitem

En este caso, hay 3 parámetros de query:

• needy, unstr requerido.
• skip, unint con un valor por defecto de0.
• limit, unint opcional.