FastAPI Souce: https://github.com/tiangolo/fastapi FastAPI Document: https://fastapi.tiangolo.com
Target: Query Parameters
FastAPI tutorial notes. Basically, I refer to the official tutorial of Fast API, but I omit some parts or change the order for my own learning. Please refer to the official documentation for the correct and detailed information.
Since I am a beginner of Web & Python and rely on Google and DeepL for translation, I would appreciate it if you could point out any mistakes.
Click here for previous notes
-FastAPI Tutorial Memo Part 1 Installation -FastAPI Tutorial Memo Part 2 Path Parameters
Ubuntu 20.04 LTS Python 3.8.2 pipenv 2018.11.26
--Understanding how to use ** Query Parameter ** in FastAPI
Intro Last time (FastAPI Tutorial Memo 2 Path Parameters), I learned how to pass ** Path Parameters ** as function parameters. This time I would like to learn how to pass ** Query parameters **.
In FastAPI, if you declare a parameter that is not a Path parameter as a function argument, it will be automatically interpreted as a ** Query parameter **. Check the code below.
main.py
from fastapi import FastAPI
app = FastAPI()
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10): # <-Query parameter is specified.
return fake_items_db[skip : skip + limit]
In HTTP URIs, ** queries ** are basically expressed by connecting key and value pairs that follow ? with =.
If you specify more than one, separate the URIs with &.
If you want to match the above code, for example, the following URL is assumed:
http://127.0.0.1:8000/items/?skip=0&limit=10
The ** Query parameter ** in this case is
--skip with a value of 0
--limit with a value of 10
Are passed to the function.
Since these are part of the URL, they should normally be interpreted as strings (str).
However, in the above code, when specifying a parameter as an argument, it is declared with the Python type ʻint type, so the parameter is converted and verified to the ʻint type.
This means that the following benefits applied with the ** Path parameter ** also apply to the ** Query parameter **.
--Editor support --Data "parsing" (analysis) --Data verification --Automatic documentation
In addition, these advantages are supported not only by Path and Query but also by various parameters handled by Fast API.
The ** Query parameter ** is not fixed by the URI path, but is an optional setting, so you can specify the default value.
In the code above, you can see that the default values are skip = 0 and limit = 10.
So a URL like this:
http://127.0.0.1:8000/items/
When accessed from a browser
http://127.0.0.1:8000/items/?skip=0&limit=10
The above two URLs have the same output.
Also, for example, the following URL:
http://127.0.0.1:8000/items/?skip=20
If you access to, the parameters of the function will be:
--skip = 20 set in the URL
--Default value limit = 10
Optional parameters
It is also possible to declare ** Query parameters ** that can be used as options by setting the default value to None.
As an example, check the code below.
main.py
from typing import Optional #Import Optional from typing package
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Optional[str] = None): #Query parameter"q"Is declared as an optional parameter
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
In this case, the function parameter q is treated as an option and is treated as None by default.
Notice that the Fast API understands that ʻitem_id is a ** Path parameter ** and q` is a ** Query parameter ** instead of a ** Path parameter **. ..
Also, the Fast API recognizes that q is an optional parameter just by declaring = None.
ʻOptional is not used by the Fast API itself. The purpose of making it explicit as ʻOptional [str] is that the editor support can detect the error in advance.
You can declare the bool type as a ** Query parameter **, in which case the Fast API will convert the parameter to a suitable form.
As an example, check the code below.
main.py
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
#Bool type is specified in the query parameter of the argument
async def read_item(item_id: str, q: Optional[str] = None, short: bool = False):
item = {"item_id": item_id}
if q:
item.update({"q": q})
if not short:
item.update(
{"description": "This is an amazing item that has a long description"}
)
return item
For such code, you can access it as follows:
http://127.0.0.1:8000/items/foo?short=1http://127.0.0.1:8000/items/foo?short=Truehttp://127.0.0.1:8000/items/foo?short=truehttp://127.0.0.1:8000/items/foo?short=onhttp://127.0.0.1:8000/items/foo?short=yesFor these URLs, all parameters short are treated as True with a bool value. (The same is true if the first letter is changed from lowercase to uppercase)
If the value is other than the above, it will be False.
In this way, when bool type is specified in ** Query parameter **, conversion is performed by Fast API.
In FastAPI, it works fine even if you declare multiple ** Path parameters ** and ** Query parameters ** at the same time as function arguments. You also don't have to declare them in any particular order. This is because FastAPI recognizes parameters by name.
For example, if you have code like this:
main
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/{user_id}/items/{item_id}") # <- {user_id}When{item_id}をPathパラメータWhenして指定
async def read_user_item(
user_id: int, item_id: str, q: Optional[str] = None, short: bool = False # <-Not a Path parameter"q"When"short"はQueryパラメータWhenして扱う
):
item = {"item_id": item_id, "owner_id": user_id}
if q:
item.update({"q": q})
if not short:
item.update(
{"description": "This is an amazing item that has a long description"}
)
return item
In this case, there is no problem even if you change the order of the function arguments. FastAPI recognizes each parameter based on the name of the parameter.
If you declare a default value with a parameter other than Path (although we're only learning Query parameters at this time), that parameter is no longer a mandatory parameter. This is because if the parameter is omitted, the default value is specified.
You can also declare a parameter as an optional parameter without adding a specific value by setting the default value to None.
Then, what to do when you want to set ** Query parameter ** as an indispensable parameter that cannot be omitted, you can do it by not declaring the default value.
main
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str): # <-Declaring the parameter needley without specifying a default value
item = {"item_id": item_id, "needy": needy}
return item
The needy parameter above is declared as a required str type ** Query parameter **.
If you have a URL like this:
http://127.0.0.1:8000/items/foo-item
If you open in a browser, you will see the following error because the required parameter needy has not been added.
{
"detail": [
{
"loc": [
"query",
"needy"
],
"msg": "field required",
"type": "value_error.missing"
}
]
}
needy is a required parameter, so you need to specify it in the URL as below:
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
This URL should look like this:
{
"item_id": "foo-item",
"needy": "sooooneedy"
}
Of course, it is possible to define required parameters, parameters with default values, and optional parameters at the same time.
main
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_user_item(
item_id: str, needy: str, skip: int = 0, limit: Optional[int] = None # <-
):
item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
return item
In the code above, three query parameters are declared.
--needy: Required parameter of type str (without default value)
--skip: ʻinttype parameter with default value0 --limit: ʻint type optional parameter
You can use ʻEnum` in ** Query parameter ** as well as ** Path parameter **. See Path Parameters for details.
This time I learned how to use the ** Query parameter **. All the code used in this article is taken from the Official Documentation (https://fastapi.tiangolo.com/tutorial/query-params/), I have confirmed that it works in my local environment.
Next time, we will study ** Request Body **.
Recommended Posts