FastAPI 02. 경로, 쿼리 매개변수 검증

API를 만들게 되면 경로 매개변수나 쿼리 매개변수 검증이 필요한 경우가 있다. 예를 들어 경로 매개변수가 0 이상 정수값이어야 한다거나, 쿼리 매개변수의 문자열의 길이를 제한하는 등 검증을 한다. FastAPI에서는 Query, Path라는 편리한 방법을 제공한다.

쿼리 파라미터

@app.get("/items/")
async def read_item(q: str):
    return q

우선 다음과 같은 API에서 시작하자, 하나의 쿼리 파라미터 q를 입력받는 경우를 가정했을 때 상황을 구체화 해보자.

from fastAPI import FastAPI, Query

@app.get("/items/")
async def read_item(q: str = Query(defalut=None)):
    return q

함수에서 변수로만 선언하여 쿼리 파라미터임을 나타낼 수 있지만, 해당 변수를 q = Query() 형식으로 두어 쿼리 파라미터임을 확실하게 보여줄 수 있고, 추가적인 검증에도 사용할 수 있다. 예를 들어 위에서 default값을 활용하면 입력이 없을 때 기본값을 사용할지 정의할 수 있다. 또한 min_length, max_length 등을 활용하여 문자열 길이 검증에 사용할 수 있고, regex를 사용하면 정규식 매칭을 활용할 수 있다.

# required
q: str = Query()
q: str = Query(default=...)

또한 파라미터의 선택적 또는 필수적 요소로 설정할 수 있다. FastAPI 공식문서에서 더욱 다양한 방법을 제공하는데, 그중 필수 요소로 설정하는 방식을 다음과 같이 할 수 있다.

경로 파라미터

from fastAPI import FastAPI, Query, Path

@app.get("/items/{item_id}")
async def read_item(
    item_id: int = Path(gt=0, le=1000),
    q: str = Query(defalut=None),
):
    return {"item_id": item_id, "q": q}

경로 파라미터 역시 Path를 사용하여 명시적으로 활용할 수 있다. 숫자의 경우 gt, ge, lt, le를 사용하여 초과, 이상, 미만, 이하를 나타낼 수 있다.

요약

Query, Path 함수를 사용하여 명시적으로 표현 및 데이터 검증에 활용할 수 있다.