[파이썬] FastAPI - 라우팅

시작에 앞서

해당 내용은 <가장 빠른 풀스택을 위한 Flask & FastAPI>, Dave Lee 지음. BJ Public 출판.
내용을 토대로 작성되었습니다. 보다 자세한 사항은 해당 교재를 참고하시기 바랍니다.

---

라우팅

 

라우팅은

클라이언트로부터 오는 HTTP 요청을 알맞은 로직(함수나 메서드)으로 연결하는 과정을 의미한다.

▶ 특정 URL을 어떤 함수가 처리할지를 정의하는 것이며, 클라이언트의 요청을 적절한 처리 로직에 연결하는 기능을 수행하는 것이다.

 

FastAPI에서는 데코레이터를 사용하여 라우팅을 간단하게 할 수 있다.

---

기본 라우팅

 

가장 간단한 형태의 라우팅은 HTTP GET 메서드를 사용하는 경우이다.

 

[루트 URL에 GET 요청을 하면 응답을 보내는 예시]

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
	return {"message": "Hello, FastAPI"}

---

경로 매개변수 & 쿼리 매개변수

 

FastAPI는 사용자의ㅏ 요청을 구체적으로 명시하기 위해 두 가지 종류의 매개변수를 사용한다.

경로 매개변수 / 쿼리 매개변수

이는 각각 URL의 경로와 쿼리 스트링으로부터 정보를 수집하는 역할을 하며, FastAPI는 이 두 가지 매개변수를 명확하게 구분하여 사용함으로써 API의 정확성과 편의성을 대폭 향상시킨다.

 

• 경로 매개변수(파라미터): URL의 특정 부분을 변수로써 사용하여 동적으로 변할 수 있는 값을 처리할 때 사용되며, URL의 구조 안에 직접 포함되어 있기 때문에 경로의 일부로 인식된다.

예를 들어, /items/1 과 /items/2 라는 URL에서 1과 2는 각각 다른 아이템을 식별하는 고유한 값으로, 경로 매개변수 item_id를 통해 서버에 전달된다.

@app.get("/items/{item_id}")
def read_item(item_id):
	return {"item_id": item_id}

 

위 코드에서 {item_id}는 경로 매개변수를 정의하는 부분으로, 사용자가 방문하는 URL의 해당 부분에 있는 값을 int 타입으로 read_item() 함수에 전달한다.

 

FastAPI를 사용하여 여러 개의 경로 매개변수를 포함하는 라우트를 만들 때, URL의 여러 부분을 동적으로 캡처하여 함수에 전달할 수 있다.

예) /users/123/items/foobar 의 URL에 엑세스 하는 경우

▶ 사용자 식별자(user_id), 아이템 이름(item_name)의 두 개의 경로 매개변수가 있다.

 

복수의 경로 매개변수를 사용하는 것은 웹 API에서 매우 일반적이며, 이를 통해 클라이언트는 서버에 특정 자원을 정확하게 요청할 수 있다. 서버는 이 정보를 사용하여 요청 받은 자원을 찾아 응답할 수 있다.

이 방식은 URL 경로의 의미를 더욱 명확하게 하고, 웹 서비스의 구조를 이해하기 쉽게 만든다.

---

• 쿼리 매개변수(파라미터): URL의 경로 이후 ?로 시작하는 부분에 정의되며, 키-값 쌍의 형태로 정보를 전달하는 데 사용. 매개변수들은 주로 필터링, 정렬, 페이지네이션 등과 같이 요청을 더 세부적으로 조정할 필요가 있을 때 활용된다.

쿼리 매개변수는 선택적이며, 동일한 경로에 대해 다양한 연산을 가능하게 한다.

@app.get("/items/")
def read_items(skip, limit):
	return {"skip": skip, "limit": limit}

▶ 위 예시에서 skip과 limit 매개변수는 쿼리 매개변수이다.

사용자가 /items/?skip=5&limit=5 와 같이 요청을 보내면, 서버는 이를 해석하여 skip과 limit에 해당하는 값을 함수의 매개변수로 사용한다.

 

◆ 쿼리 매개변수의 기본값 설정에 따른 코드 작성

첫 번째 코드는 skip과 limit 매개변수에 기본값이 설정되어 있지 않다.

@app.get("/items/")
def read_items(skip, limit):
	return {"skip": skip, "limit": limit}

이는 클라이언트가 이 매개변수들을 반드시 URL 쿼리에 포함하여 값을 제공해야 함을 의미한다.

 

두 번째 코드는 skip과 limit 매개변수에 기본값이 설정되어 있다.

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

클라이언트가 이 값들을 제공하지 않아도 기본값이 0과 10이 사용된다. 이는 클라이언트가 매개변수를 생략해도 요청이 성공하며, 서버는 기본 설정된 값으로 응답을 반환한다.

---

curl을 이용한 테스트

 

지금까지의 라우팅 코드를 모아서 FastAPI 코드를 작성하고 실행해본다.

from fastapi import FastAPI #FastAPI 라이브러리 import

app = FastAPI() # FastAPI 인스턴스 생성

@app.get("/") # HTTP GET 요청을 "/" 경로로 받을 준비
def read_root(): # 해당 요청을 처리할 함수 정의
    return {"message": "Hello, FastAPI"} #JSON 형태의 응답 반환

@app.get("/items/{item_id}")
def read_items(item_id):
	return {"item_id": item_id}

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

 

이 코드를 main.py로 저장한 후, 터미널에서 실행한다.

uvicorn main:app --reload

 

◆ 루트 URL에 GET 요청을 보내 라우팅 확인

curl http://127.0.0.1:8000/

 

◆ 경로 매개변수 item_id를 5로 지정하여 테스트

http://127.0.0.1:8000/items/5

 

◆ 쿼리 매개변수 skip을 20, limit을 2로 설정하여 테스트

curl "http://127.0.0.1:8000/items/?skip=20&limit=2"

 

◆ skip과 limit을 설정하지 않은 경우 기본값 출력

curl "http://127.0.0.1:8000/items/"

---

다음 내용

[파이썬] FastAPI - 타입 힌트