Fast API 사용해보기 - Query Parameters and String Validations

FastAPI 에서는 파라미터에 추가 정보를 선언하거나 검증을 할 수 있습니다.

from typing import Optional
from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

위 처럼 query parameter q가 Optional[str] 타입임을 지정할 수 있습니다. (str 타입이지만 optional 파라미터이고, 기본값은 None)

q 파라미터는 optional 파라미터이지만, 만약 값이 주어졌을 경우 문자열의 길이가 50자를 넘지 않게끔 검증을 추가할 수 있습니다.

from typing import Optional
from fastapi import FastAPI, Query


app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

FastAPI 에서 제공하는 Query를 활용하면 이와 같은 검증을 추가할 수 있습니다.
따라서

q: Optional[str] = Query(None)

q: Optional[str] = None

두 선언은 같은 의미를 가집니다.

max_length 이외에도 min_length 같은 검증을 추가할 수 있습니다.
만약 유효하지않은 데이터가 입력된다면 오류가 발생합니다.

from typing import Optional
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, min_length=3, max_length=50)):

    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

또한 파라미터를 정규표현식과도 매칭시킬 수 있습니다.

from typing import Optional
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(None, min_length=3, max_length=50, regex="^fixedquery$")

):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

만약 Query를 사용하면서 required 파라미터를 사용하고 싶다면 기본 값 대신 Ellipsis (...)를 사용하면 됩니다.

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(..., min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Query로 query parameter를 정의하면 list 혹은 여러 값을 받도록 선언할 수 있습니다.

from typing import List, Optional
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")

async def read_items(q: Optional[List[str]] = Query(None)):
    query_items = {"q": q}
    return query_items

위와 같이 정의했을 때 URL은

http://localhost:8000/items/?q=foo&q=bar

형식을 가지며 q 파라미터는 여러 값을 list 형태로 받을 수 있습니다.

{
  "q": [
    "foo",
    "bar"
  ]
}

여러 값을 받을 때 기본 값은

from typing import List
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: List[str] = Query(["foo", "bar"])):
    query_items = {"q": q}
    return query_items

위 처럼 정의할 수 있습니다. 타입은 List[str] 말고도 list로 지정할 수 있습니다.

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list = Query([])):
    query_items = {"q": q}
    return query_items

파라미터에는 문서화를 위해 추가적인 정보들을 넣어 줄 수도 있습니다.

from typing import Optional
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(
        None,
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

FastAPI에서는 item-query 같은 파라미터를 넣어주고 싶을때, 파이썬에서는 유효하지 않은 형식이지만 alias를 지정해줌으로써 item_query 형태로 변환하여 받을 수 있습니다.

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, alias="item-query")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

또한 만약 deprecated 되는 파라미터를 명시하고 싶을 때는 deprecated=True를 활용해 문서에 명확히 표현할 수 있습니다.

from typing import Optional
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(
        None,
        alias="item-query",
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
        max_length=50,
        regex="^fixedquery$",
        deprecated=True,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results