[FastAPI-②] 파이썬 FastAPI 요청 처리 심화 – 경로와 쿼리 매개변수, 다양한 요청 방식

파이썬 FastAPI 요청 처리 심화 – 경로와 쿼리 매개변수, 다양한 요청 방식

FastAPI에서의 요청 처리는 단순한 URL 호출을 넘어, 변수, 쿼리, 그리고 다양한 HTTP 메서드로 확장됩니다. 그 핵심을 이번 글에서 파헤쳐볼게요!

 

 

안녕하세요, 개발자 여러분 😊

이번 글에서는 FastAPI의 진짜 매력을 느낄 수 있는 "요청 처리 심화" 파트를 다뤄보려 해요.

단순히 /hello 경로만 호출해서 문자열 반환하는 것에 만족하셨다면, 이제 한 단계 더 나아가 보죠.

경로 변수와 쿼리 파라미터, 그리고 다양한 HTTP 메서드를 활용한 CRUD API 설계까지, 여러분이 실전에서 꼭 만나게 될 상황들을 중심으로 소개합니다.

개발자라면 누구나 REST API를 다루게 되는데, FastAPI만큼 직관적이고 깔끔하게 처리할 수 있는 프레임워크는 드물어요.

이 글을 끝까지 따라오시면, 여러분도 FastAPI로 유연하고 강력한 API를 만드는 데 자신감을 가지게 될 거예요!

목차

1. 경로 변수(Path Parameters)의 개념과 활용 2. 쿼리 파라미터(Query Parameters)의 처리와 기본값 설정 3. 다양한 HTTP 메서드로 API 설계하기 4. 간단한 Todo 리스트 API 실습 5. 응답 코드 설정과 HTTPException 사용법 6. 자동 문서화 /docs로 확인하는 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() 함수를 활용해 경로 변수에 대해 더 정교한 검증을 할 수 있도록 지원해요.

예를 들어,

최소값, 최대값을 설정하거나 설명을 추가할 수 있답니다.

이건 나중에 심화로 다룰 테니 일단 기본 개념만 확실히 익혀둬요!

✅ 요약 정리

1. {변수명}으로 경로에 변수 삽입 가능
2. 타입 힌트 사용 시 자동 변환 및 검증 처리
3. 잘못된 타입 전달 시 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자 이하일 때만 유효하게 동작하게 만들 수 있어요!

✅ 요약 정리

1. 경로에 포함되지 않은 인자는 자동으로 쿼리 파라미터로 처리
2. 기본값을 지정해 선택적 파라미터 구현 가능
3. 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}

💡 테스트 방법

1. 터미널에서 uvicorn main:app --reload로 실행
2. http://127.0.0.1:8000/docs로 접속
3. 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"
}

✅ 요약 정리

1. status_code 파라미터로 성공 응답 상태 지정 가능 (예: 201)
2. 에러 상황에는 HTTPException을 활용해 상태 코드 + 상세 메시지 전달
3. 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 에러가 발생할 수 있다고 하면, 이 상황도 문서 상에 함께 노출돼서 클라이언트 개발자도 명확히 이해할 수 있습니다.

✅ 요약 정리

1. FastAPI는 기본적으로 Swagger UI 기반의 문서 제공
2. 각 API의 경로, 메서드, 파라미터, 응답을 자동 문서화
3. /docs 페이지에서 직접 테스트 가능

🚀 자동 문서화 기능은 FastAPI의 가장 큰 장점 중 하나입니다.

      실무에서는 팀원들과 협업하거나 외부 개발자에게 API를 설명할 때 이 기능이 정말 유용하게 쓰이죠.

 

 

마무리

여기까지 따라오셨다면 FastAPI의 요청 처리 방식에 대해 꽤나 깊이 있게 이해하셨을 거예요.

단순한 라우팅을 넘어, 경로 변수와 쿼리 파라미터를 어떻게 활용할 수 있는지, 그리고 다양한 HTTP 메서드와 응답 코드 설정, 예외 처리, 자동 문서화까지…

이 모든 요소들이 잘 어우러져야 실용적이고 유지보수하기 쉬운 API를 만들 수 있습니다.

FastAPI는 배우기도 쉽고, 작성한 코드가 곧 문서가 되어주기 때문에 백엔드 API를 처음 만드는 분들에게도 정말 좋은 선택이에요.

 

다음 단계에서는 Pydantic 모델을 활용한 본문(JSON) 처리와 입력 검증에 대해 다룰 예정입니다.

점점 더 실무에 가까운 내용으로 나아가니, 기대해 주세요!

 

📌 오늘 배운 내용은 실제 웹 서비스,

      예를 들어 블로그 API나 게시판 API처럼 사용자와 데이터를 주고받는 시스템의 기본이 되는 부분입니다.

      꼭 복습하시고, 실습도 꼭 해보세요!