[FastAPI] 경로 매개변수 & 쿼리 매개변수

이번에 소개할 내용은 경로 매개변수와 쿼리 매개변수입니다. 두 매개변수 모두 HTTP 요청을 통해서 데이터를 전달한다는 점과 URL을 통해 입력이 들어온다는 공통점이 있습니다.

경로 매개변수

경로 매개변수는 API 경로에서 동적으로 변할 수 있는 부분을 정의할 때 사용합니다. 정해진 경로에 변수를 넣고, FastAPI가 해당 위치의 값을 추출해서 사용합니다. 정해진 경로는 '{ }' 를 통해 설정해 줍니다.

코드 예시)

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def read_user(user_id: int):
	return {"user_id":user_id}

위의 user_id 처럼 형식을 지정해서 사용할 수 있습니다.

사용 예시)

GET /users/1234

 

쿼리 매개변수

쿼리 매개변수는 URL 뒤에 '?' 로 구분되는 부분에 key=value 형태로 사용됩니다. 그리고 URL 경로와는 독립적으로 동작되어 여러 개를 동시에 사용할 수 있습니다.

코드 예시)

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
	return {"skip": skip, "limit": limit}

사용 예시)

GET /itmes/?skip=5&limit=15

이렇게 '?' 뒤에 각 변수 값을 넣어주게 되면 값이 등록되고 값이 입력되지 않을 경우 기본값이 설정되게 할 수 있습니다.

 

차이점

구분	경로 매개변수	쿼리 매개변수
위치	URL 경로의 일부, 중괄호 {} 안에 정의	URL '?' 뒤에 key=value 형태
필수 여부	필수, 경로에 반드시 포함	선택, 기본값 설정 가능
목적	리소스 식별 및 경로의 변동적인 부분 처리	필터링, 검색, 정렬 등 옵션 설정에 사용
예시	/users/{user_id}	/items/?skip=0&limit=10

 

FastAPI docs

https://fastapi.tiangolo.com/ko/tutorial/path-params/

경로 매개변수 - FastAPI

https://fastapi.tiangolo.com/ko/tutorial/query-params/

쿼리 매개변수 - FastAPI