파이썬 FastAPI 요청 처리 심화 – 경로와 쿼리 매개변수, 다양한 요청 방식
FastAPI에서의 요청 처리는 단순한 URL 호출을 넘어, 변수, 쿼리, 그리고 다양한 HTTP 메서드로 확장됩니다. 그 핵심을 이번 글에서 파헤쳐볼게요!
안녕하세요, 개발자 여러분 😊
이번 글에서는 FastAPI의 진짜 매력을 느낄 수 있는 "요청 처리 심화" 파트를 다뤄보려 해요.
단순히 /hello 경로만 호출해서 문자열 반환하는 것에 만족하셨다면, 이제 한 단계 더 나아가 보죠.
경로 변수와 쿼리 파라미터, 그리고 다양한 HTTP 메서드를 활용한 CRUD API 설계까지, 여러분이 실전에서 꼭 만나게 될 상황들을 중심으로 소개합니다.
개발자라면 누구나 REST API를 다루게 되는데, FastAPI만큼 직관적이고 깔끔하게 처리할 수 있는 프레임워크는 드물어요.
이 글을 끝까지 따라오시면, 여러분도 FastAPI로 유연하고 강력한 API를 만드는 데 자신감을 가지게 될 거예요!
목차
1. 경로 변수(Path Parameters)의 개념과 활용
FastAPI를 사용하다 보면 경로(URL) 안에 직접 데이터를 넣어서 API 요청을 날리는 경우가 정말 많습니다.
예를 들어
사용자 정보를 조회할 때 /users/10 이런 식으로 요청을 보내곤 하죠.
여기서 10은 경로 변수입니다.
FastAPI에서는 /users/{user_id}와 같이 중괄호({})를 사용해서 경로 변수를 선언할 수 있고, 해당 값은 함수 인자에서 받아올 수 있어요.
여기에 타입 힌트까지 붙이면 더 강력해지죠.
다음 예제를 함께 살펴볼게요.
📌 실습 예제 – 사용자 ID로 조회하기
@app.get("/users/{user_id}")
def read_user(user_id: int):
return {"user_id": user_id}
👉 예를 들어 http://127.0.0.1:8000/users/7에 요청하면, {"user_id": 7} 이 응답됩니다!
🎯 경로 변수의 특징 정리
- URL 경로 내에 값을 직접 삽입할 수 있다.
-
user_id: int처럼 타입 지정 가능 → FastAPI가 자동으로 검증 - 잘못된 타입 요청 시 자동으로 422 오류 반환됨
📎 참고 팁
FastAPI는 Pydantic의 Path() 함수를 활용해 경로 변수에 대해 더 정교한 검증을 할 수 있도록 지원해요.
예를 들어,
최소값, 최대값을 설정하거나 설명을 추가할 수 있답니다.
이건 나중에 심화로 다룰 테니 일단 기본 개념만 확실히 익혀둬요!
✅ 요약 정리
{변수명}으로 경로에 변수 삽입 가능- 타입 힌트 사용 시 자동 변환 및 검증 처리
- 잘못된 타입 전달 시 422 Unprocessable Entity 오류
2. 쿼리 파라미터(Query Parameters)의 처리와 기본값 설정
FastAPI에서는 경로 이외에도 쿼리 파라미터를 아주 쉽게 처리할 수 있어요.
우리가 웹사이트에서 흔히 보는 ?page=1&size=10 같은 주소 기억나시죠?
이런 식의 URL에서 page나 size 같은 값들을 FastAPI는 아주 자연스럽게 함수 인자로 넘겨줍니다.
FastAPI는 함수에 정의된 매개변수가 경로 변수와 일치하지 않으면 자동으로 쿼리 문자열로 간주해서 값을 찾아요.
즉, /items?skip=5&limit=20 요청은 아래 함수로 처리할 수 있습니다.
🔍 실습 예제 – 아이템 페이징 처리
@app.get("/items")
def read_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}
🔗 http://127.0.0.1:8000/items?skip=5&limit=20로 접속해보세요!
결과는 {"skip": 5, "limit": 20}으로 출력될 거예요.
⚙️ 기본값과 선택적 파라미터
매개변수에 = 기본값을 지정하면, 그 값은 선택적 파라미터가 됩니다.
예를 들어
위의 skip: int = 0은 값을 주지 않아도 기본적으로 0으로 설정돼요.
그래서 /items만 호출해도 오류 없이 작동합니다.
🎯 쿼리 파라미터의 활용 예
- 게시글 목록 조회 시 페이징 처리 (
page,size) - 상품 검색 시 필터링 옵션 전달 (
keyword,category등)
📎 고급 활용 – Query 함수로 유효성 검증
FastAPI는 Query()라는 유틸리티를 제공해요.
이걸 쓰면 최소값, 최대값, 정규식 검증 등 다양한 제약 조건을 설정할 수 있어요.
예를 들어:
from fastapi import Query
@app.get("/search")
def search_items(q: str = Query(..., min_length=3, max_length=50)):
return {"query": q}
▶️ 이처럼 Query를 활용하면 검색어가 최소 3자 이상, 50자 이하일 때만 유효하게 동작하게 만들 수 있어요!
✅ 요약 정리
- 경로에 포함되지 않은 인자는 자동으로 쿼리 파라미터로 처리
- 기본값을 지정해 선택적 파라미터 구현 가능
Query()를 통해 유효성 검사와 문서화 가능
3. 다양한 HTTP 메서드로 API 설계하기
웹 개발을 하다 보면 단순한 데이터 조회(GET) 외에도, 데이터를 생성, 수정, 삭제하는 다양한 작업이 필요하죠.
이럴 때 사용하는 것이 바로 HTTP 메서드입니다.
FastAPI는 @app.post(), @app.put(), @app.delete() 같은 데코레이터로 쉽게 메서드를 구분해 구현할 수 있어요.
보통 REST API에서 CRUD 작업은 다음과 같은 매핑으로 이루어져요:
- POST – 자원 생성(Create)
- GET – 자원 조회(Read)
- PUT / PATCH – 자원 수정(Update)
- DELETE – 자원 삭제(Delete)
🛠 실습 예제 – Todo 리스트 API
이제 간단한 Todo 리스트 API를 만들어볼게요.
아직 데이터베이스는 연결하지 않고, 메모리 안에 리스트로 관리할 거예요.
from typing import List
todos: List[str] = []
@app.post("/todos")
def create_todo(item: str):
todos.append(item)
return {"msg": "Todo created", "item": item}
@app.get("/todos")
def read_todos():
return {"todos": todos}
@app.delete("/todos/{index}")
def delete_todo(index: int):
if 0 <= index < len(todos):
removed = todos.pop(index)
return {"msg": "Todo deleted", "item": removed}
else:
return {"msg": "Index out of range", "index": index}
📌 포인트 정리
- POST 요청으로 할 일(item)을 생성할 수 있어요.
- GET 요청으로 현재 저장된 모든 할 일들을 조회할 수 있어요.
- DELETE 요청으로 특정 인덱스의 할 일을 삭제할 수 있어요.
✨ 추후에는 item을 문자열 대신 JSON 구조로 받고, 유효성 검사도 추가할 예정입니다.
지금은 기본 동작 원리를 익히는 게 목표예요!
4. 간단한 Todo 리스트 API 실습
이번에는 앞서 배운 내용을 바탕으로 아주 간단한 Todo API를 하나씩 구현해볼 거예요.
복잡한 데이터베이스는 사용하지 않고, 우선 파이썬 리스트에 데이터를 저장하면서 개념과 흐름을 익히는 데 집중해봅시다.
📝 기능 목록
- POST – 새로운 Todo 항목 추가
- GET – 전체 Todo 항목 조회
- DELETE – 특정 항목 삭제
이 Todo API는 FastAPI의 기본 기능만으로도 손쉽게 만들 수 있어요.
아래는 전체 구현 코드입니다.
from typing import List
from fastapi import FastAPI
app = FastAPI()
todos: List[str] = []
@app.post("/todos")
def create_todo(item: str):
todos.append(item)
return {"msg": "Todo created", "item": item}
@app.get("/todos")
def read_todos():
return {"todos": todos}
@app.delete("/todos/{index}")
def delete_todo(index: int):
if 0 <= index < len(todos):
removed = todos.pop(index)
return {"msg": "Todo deleted", "item": removed}
else:
return {"msg": "Index out of range", "index": index}
💡 테스트 방법
- 터미널에서
uvicorn main:app --reload로 실행 http://127.0.0.1:8000/docs로 접속- Swagger UI에서 API 직접 테스트
📎 실전 팁
현재는 문자열 하나만 다루고 있지만, 보통은 title, description, due_date 같은 구조화된 데이터를 다루게 돼요.
그래서 다음에는 Pydantic 모델을 이용한 JSON 구조 요청 처리도 이어서 다뤄볼 거예요.
🛠 지금은 구조보다 흐름과 메서드별 동작 방식을 이해하는 게 포인트입니다!
5. 응답 코드 설정과 HTTPException 사용법
API를 개발하다 보면 어떤 작업이 성공했는지, 실패했는지 클라이언트에게 명확한 상태 코드로 알려주는 게 매우 중요해요.
FastAPI에서는 status_code 파라미터나 HTTPException 클래스를 이용해서 간단하게 응답 상태를 설정할 수 있습니다.
🔢 status_code 파라미터
기본적으로 FastAPI는 정상 응답 시 200 OK 상태 코드를 반환하지만, POST 요청에서 자원이 성공적으로 생성됐다는 의미로는 201 Created를 사용하는 것이 더 적절해요.
from fastapi import FastAPI
app = FastAPI()
@app.post("/todos", status_code=201)
def create_todo(item: str):
return {"msg": "Todo created", "item": item}
📍 위처럼 status_code=201을 명시하면 Swagger 문서(/docs)에서도 명확히 표현되고, 실제 응답 헤더에도 적용돼요.
🚨 HTTPException으로 에러 처리하기
클라이언트가 잘못된 요청을 보냈을 때, 그냥 텍스트로 알려주는 대신 HTTPException을 활용하면 더 표준적인 방식으로 에러를 응답할 수 있어요.
FastAPI는 이 기능을 아주 깔끔하게 지원합니다.
from fastapi import HTTPException
@app.delete("/todos/{index}")
def delete_todo(index: int):
if 0 <= index < len(todos):
removed = todos.pop(index)
return {"msg": "Todo deleted", "item": removed}
else:
raise HTTPException(status_code=404, detail="Todo index out of range")
❗ 이렇게 하면 404 Not Found 상태 코드와 함께 에러 메시지가 JSON 형태로 전달됩니다.
🧾 예시 응답 구조
{
"detail": "Todo index out of range"
}
✅ 요약 정리
- status_code 파라미터로 성공 응답 상태 지정 가능 (예: 201)
- 에러 상황에는 HTTPException을 활용해 상태 코드 + 상세 메시지 전달
- Swagger 문서에 자동으로 반영되어 테스트가 쉬움
🧠 상태 코드와 예외 처리는 API 설계에서 신뢰도를 높이는 핵심 요소예요.
놓치지 말고 꼭 적용해보세요!
6. 자동 문서화 /docs로 확인하는 API 인터페이스
FastAPI를 처음 접했을 때 가장 감탄했던 기능 중 하나가 자동 API 문서화였어요.
우리가 별도로 Swagger를 설정하지 않아도, FastAPI는 프로젝트를 실행하면 /docs 경로에 멋진 UI를 제공해줍니다.
이 문서화 기능은 Swagger UI를 기반으로 하고 있으며, OpenAPI 스펙을 따르기 때문에 API를 설계, 테스트, 설명하는 데 매우 유용합니다.
📘 /docs에서 확인할 수 있는 정보들
- 등록된 모든 API 경로 (GET, POST, DELETE 등)
- 각 API가 사용하는 요청 파라미터와 타입
- 응답 형식 및 예시 JSON
- 상태 코드 정보 및 설명
📌 테스트도 직접 가능!
Swagger UI의 진짜 매력은 단순 문서화가 아니라 인터랙티브한 테스트 기능입니다.
각 API 아래에 있는 "Try it out" 버튼을 누르면, 실제로 파라미터를 입력해보고 바로 응답 결과를 확인할 수 있어요.
🧪 서버를 켜둔 상태에서 http://127.0.0.1:8000/docs 로 접속하면 지금까지 만든 Todo API를 바로 테스트할 수 있습니다!
📄 응답과 상태 코드 자동 문서화
우리가 status_code나 HTTPException을 지정해 놓으면 그 정보 또한 Swagger UI에 자동으로 반영돼요.
예를 들어
Todo 삭제 API에서 404 에러가 발생할 수 있다고 하면, 이 상황도 문서 상에 함께 노출돼서 클라이언트 개발자도 명확히 이해할 수 있습니다.
✅ 요약 정리
- FastAPI는 기본적으로 Swagger UI 기반의 문서 제공
- 각 API의 경로, 메서드, 파라미터, 응답을 자동 문서화
/docs페이지에서 직접 테스트 가능
🚀 자동 문서화 기능은 FastAPI의 가장 큰 장점 중 하나입니다.
실무에서는 팀원들과 협업하거나 외부 개발자에게 API를 설명할 때 이 기능이 정말 유용하게 쓰이죠.
마무리
여기까지 따라오셨다면 FastAPI의 요청 처리 방식에 대해 꽤나 깊이 있게 이해하셨을 거예요.
단순한 라우팅을 넘어, 경로 변수와 쿼리 파라미터를 어떻게 활용할 수 있는지, 그리고 다양한 HTTP 메서드와 응답 코드 설정, 예외 처리, 자동 문서화까지…
이 모든 요소들이 잘 어우러져야 실용적이고 유지보수하기 쉬운 API를 만들 수 있습니다.
FastAPI는 배우기도 쉽고, 작성한 코드가 곧 문서가 되어주기 때문에 백엔드 API를 처음 만드는 분들에게도 정말 좋은 선택이에요.
다음 단계에서는 Pydantic 모델을 활용한 본문(JSON) 처리와 입력 검증에 대해 다룰 예정입니다.
점점 더 실무에 가까운 내용으로 나아가니, 기대해 주세요!
📌 오늘 배운 내용은 실제 웹 서비스,
예를 들어 블로그 API나 게시판 API처럼 사용자와 데이터를 주고받는 시스템의 기본이 되는 부분입니다.
꼭 복습하시고, 실습도 꼭 해보세요!
'Python > Python 웹프로그래밍' 카테고리의 다른 글
| [FastAPI-④] 파이썬 FastAPI 데이터베이스 연동 – SQLAlchemy ORM 시작 (0) | 2025.04.16 |
|---|---|
| [FastAPI-③] 파이썬 FastAPI Pydantic을 통한 데이터 모델링과 검증 (0) | 2025.04.16 |
| [FastAPI-①] FastAPI로 배우는 REST API 개발 입문 (0) | 2025.04.16 |
| [Flask-⑧] Flask 웹 애플리케이션 배포 및 전체 개발 여정 마무리 (2) | 2025.04.15 |
| [Flask-⑦] Flask 확장으로 게시판 프로젝트 고도화하기 (0) | 2025.04.15 |
