파이썬 FastAPI Pydantic을 통한 데이터 모델링과 검증

FastAPI의 진짜 힘은 바로 Pydantic에 있다!
데이터를 자동으로 검증하고, 문서화까지 완벽하게 해주는
이 강력한 조합을 여러분은 알고 계셨나요?

안녕하세요, 여러분!

이번 글에서는 FastAPI에서 가장 자주 사용되는 기능 중 하나인 Pydantic 기반의 데이터 모델링과 검증에 대해 알아보려 합니다.

FastAPI를 처음 접할 땐 간단한 라우팅으로 시작하지만, 실제 프로젝트로 들어가면 사용자 입력 데이터의 유효성을 검증하고 그에 맞는 응답 모델을 처리하는 것이 핵심이 됩니다.

이 모든 과정을 도와주는 것이 바로 Pydantic이죠. 특히 초보 개발자들에게는 서버로 들어오는 요청이 어떤 구조인지, 그 구조가 올바른지 자동으로 확인해주는 기능은 정말 고마운 존재예요.

예외 처리, 직렬화, 문서 자동화까지 한 번에 해결할 수 있으니, 놓칠 수 없겠죠?

1. Pydantic BaseModel 소개와 특징 ✨

FastAPI의 진짜 매력은 어디에 있을까요? 바로 Pydantic을 활용한 자동 데이터 검증 기능에 있습니다.

Python에서 데이터 모델을 정의할 때 많은 분들이 dataclass를 사용해봤을 텐데요, Pydantic은 거기에 한 단계 더 나아가 유효성 검사, 직렬화/역직렬화, 문서화까지 제공해주는 놀라운 도구입니다.

📌 BaseModel이란?

Pydantic의 핵심은 BaseModel입니다.

BaseModel을 상속한 클래스는 구조화된 데이터 모델로서 동작하며, 입력값의 타입을 검증하고, 오류가 있으면 상세한 메시지를 반환합니다.

예를 들어, 사용자의 정보를 받는 모델을 아래처럼 정의할 수 있습니다.

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    is_active: bool = True

• id: 정수형으로 강제
• name: 문자열로 강제
• is_active: 기본값 True로 설정

이 모델에 잘못된 타입이 들어오면 어떻게 될까요?

예를 들어 User(id="abc", name=123, is_active="yes")처럼 잘못된 데이터를 전달하면,

FastAPI는 422 Unprocessable Entity 오류와 함께 자세한 오류 메시지를 응답합니다.

📈 Pydantic의 장점 요약

결론적으로,

Pydantic을 이용하면 데이터 구조 정의와 검증을 한 번에 처리할 수 있어 코드가 깔끔하고 안정적입니다.

초보자부터 숙련 개발자까지 모두에게 사랑받는 이유죠.

2. 데이터 유효성 검증과 오류 처리 🛡️

FastAPI에서 데이터 유효성 검증은 거의 자동으로 이뤄집니다.

Pydantic 모델을 엔드포인트 함수의 인자로 선언만 하면,

JSON 요청 바디를 파싱 → 타입 검증 → 오류 응답까지 단 한 줄의 추가 코드 없이 처리해주죠.

📥 요청 데이터 검증 흐름

1. 클라이언트가 JSON 데이터를 POST로 전송
2. FastAPI가 Pydantic 모델로 데이터 파싱 시도
3. 정의된 필드 타입과 다르면 422 오류 발생
4. 정상 파싱되면 뷰 함수에 모델 인스턴스를 넘겨줌

예를 들어, 사용자 이름을 문자열로 받아야 한다고 가정해봅시다.

그런데 클라이언트가 name: 1234처럼 숫자를 보내면?

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "str type expected",
      "type": "type_error.str"
    }
  ]
}

이처럼 RequestValidationError가 발생하고, FastAPI는 상세한 오류 메시지를 JSON으로 반환합니다.

개발자는 try-catch도 안 써도 되고, 클라이언트는 어떤 필드가 잘못됐는지 명확히 알 수 있죠.

⚙️ Field()를 통한 추가 제약 설정

Pydantic의 Field() 함수를 사용하면,

단순 타입 검증 외에도 문자 길이 제한, 정규표현식 검사, 기본값 설정, 예시 값 등을 지정할 수 있어요.

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(..., min_length=2, max_length=50, example="홍길동")
    email: str = Field(..., regex=r'^\S+@\S+\.\S+$', example="user@example.com")

• min_length, max_length: 문자열 길이 제약
• regex: 정규표현식으로 포맷 검증
• example: Swagger 문서에 예시로 표시

이렇게 Field를 적극 활용하면 API 입력 조건이 문서화와 동시에 자동 검증되어, 사용자와 개발자 모두에게 큰 도움이 됩니다.

✅ 요약: 검증이 자동이라 행복해요

• FastAPI + Pydantic은 요청을 자동으로 검증하고 오류를 처리한다.
• 별도의 try-except 없이도 잘못된 요청을 막을 수 있다.
• Field()로 더욱 정밀한 제약 조건을 줄 수 있다.

이제 우리는 Pydantic이 단순한 타입 검사 도구가 아니라 API의 품질과 신뢰도를 끌어올려주는 핵심 기술이라는 걸 확실히 알게 되었죠!

3. 요청 바디 모델링 방법 📦

FastAPI에서는 클라이언트로부터 JSON 형식의 데이터를 받을 때 Pydantic 모델을 직접 함수 매개변수에 선언하는 방식으로 간단하게 요청 바디를 처리할 수 있습니다.

이 방식은 특히 입력값이 여러 필드로 구성된 복합 구조일 때 더욱 유용하게 쓰이죠.

📝 모델 정의와 요청 처리 예제

예를 들어 할 일(Todo)을 등록하는 API를 만든다고 해봅시다.

title과 description을 갖는 요청 바디를 받아야 한다면 아래와 같이 모델을 정의할 수 있어요.

from pydantic import BaseModel

class TodoItemCreate(BaseModel):
    title: str
    description: str | None = None  # 선택적 필드

이제 위 모델을 FastAPI 라우터 함수에 인자로 넣으면 됩니다.

FastAPI는 클라이언트의 JSON 요청을 자동으로 파싱하고 item 객체로 만들어줍니다.

@app.post("/todos", status_code=201)
def create_todo(item: TodoItemCreate):
    todo = {"id": len(todos) + 1, "title": item.title, "desc": item.description}
    todos.append(todo)
    return todo

📌 요청 실패 시 자동 오류 처리

만약 클라이언트가 필수 필드인 title을 빠뜨리거나 문자열 대신 숫자를 보낸다면, 함수는 아예 실행되지 않고 FastAPI가 422 Unprocessable Entity 오류를 자동으로 반환합니다.

덕분에 우리는 로직에만 집중할 수 있고, 예외 처리 코드는 거의 필요 없습니다.

🧾 Swagger 문서 자동 반영

놀랍게도, 위처럼 Pydantic 모델을 선언하면 /docs 경로에서 자동 생성되는 Swagger UI 문서에도 입력 필드, 설명, 데이터 타입, 예시 값까지 모두 자동으로 표시됩니다.

즉, 코드를 짜는 것만으로 문서까지 완성되는 셈이죠.

🧠 요청 바디 처리 시 체크포인트

• BaseModel을 상속한 요청 모델을 선언하자
• 요청 본문으로 JSON 데이터가 들어오면 FastAPI가 자동으로 Pydantic 모델로 변환한다
• 모델에 정의된 조건을 만족하지 않으면 함수가 실행되지 않고 오류를 반환한다
• Field()를 이용해 제약조건과 문서 예시를 추가할 수 있다

이처럼 요청 바디에 Pydantic 모델을 사용하면 코드가 훨씬 직관적이고 안전합니다.

특히 프론트엔드와 협업할 때 Swagger 문서 덕분에 API 스펙 공유가 정말 쉬워집니다.

4. 응답 모델 지정과 데이터 직렬화 📤

FastAPI에서는 요청을 받을 때뿐만 아니라 응답을 보낼 때도 Pydantic 모델을 활용할 수 있습니다. response_model 파라미터를 사용하면 반환할 데이터의 구조를 명확히 지정할 수 있어요.

이를 통해 보안성, 신뢰성, 문서화까지 한 번에 해결됩니다.

📦 response_model의 기본 개념

API 엔드포인트에서 반환할 데이터가 어떤 구조여야 하는지를 response_model에 정의해두면,

FastAPI는 자동으로 해당 구조로 직렬화(serialization)하고 그 외의 필드는 제외합니다.

예를 들어,

다음과 같은 모델이 있다고 해볼게요.

class TodoItem(BaseModel):
    id: int
    title: str
    description: str | None = None

이제 GET 요청에 대해 이 모델을 응답 모델로 지정하면 다음과 같은 라우팅 코드를 작성할 수 있어요.

@app.get("/todos/{id}", response_model=TodoItem)
def read_todo(id: int):
    todo = get_todo_by_id(id)
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todo

여기서 todo가 dict든 ORM 객체든 상관없이 FastAPI는 TodoItem 모델 형태로 자동 변환해 응답해줍니다.

내부적으로는 dict로 변환 후 JSON으로 직렬화됩니다.

🔒 보안성을 위한 필드 필터링

예를 들어 사용자 정보를 반환할 때 DB에는 hashed_password 같은 민감한 정보가 있을 수 있습니다.

이때 응답 모델에 해당 필드를 포함하지 않으면, FastAPI는 자동으로 해당 필드를 제거하고 안전한 응답만 반환합니다.

🧩 ORM 객체 대응을 위한 orm_mode

SQLAlchemy 같은 ORM을 사용할 경우, 모델 인스턴스를 바로 반환할 수 있는데요.

이때는 응답 모델 내부에 Config 클래스를 선언해 orm_mode = True로 설정해줘야 합니다.

class TodoItem(BaseModel):
    id: int
    title: str
    description: str | None = None

    class Config:
        orm_mode = True

이 설정을 해주면 FastAPI는 ORM 객체에서 필드를 자동으로 추출해서 응답 모델로 직렬화해줍니다.

🧾 response_model이 주는 이점 정리

결론적으로 response_model은 응답을 명시적으로 통제할 수 있는 강력한 기능입니다.

특히 API 문서 자동화와 보안 강화 측면에서 필수로 활용해야 할 요소죠!

5. 인메모리 Todo API 실습 예제 🧪

이제까지 배운 내용을 바탕으로 간단한 Todo API 예제를 만들어보며 실습해볼 시간이에요.

데이터베이스 없이 인메모리 리스트를 사용하여 CRUD 기능을 구현해볼 거예요.

이 과정을 통해 Pydantic 모델을 어떻게 활용하고, FastAPI의 기능과 어떻게 연결되는지 확실히 체감할 수 있습니다.

🔧 모델 정의

from pydantic import BaseModel
from typing import List, Optional

class TodoItemCreate(BaseModel):
    title: str
    description: Optional[str] = None

class TodoItem(TodoItemCreate):
    id: int
    done: bool = False

TodoItemCreate는 생성 요청용, TodoItem은 응답 및 조회용으로 사용됩니다.

생성 시에는 ID와 완료 여부가 없기 때문에 모델을 상속 구조로 나누어 중복을 줄였습니다.

🚀 엔드포인트 구현

from fastapi import FastAPI, HTTPException

app = FastAPI()
todos: List[TodoItem] = []
current_id = 0

@app.post("/todos", response_model=TodoItem, status_code=201)
def create_todo(item: TodoItemCreate):
    global current_id
    current_id += 1
    todo = TodoItem(id=current_id, **item.dict())
    todos.append(todo)
    return todo

@app.get("/todos", response_model=List[TodoItem])
def list_todos():
    return todos

@app.get("/todos/{id}", response_model=TodoItem)
def get_todo(id: int):
    for todo in todos:
        if todo.id == id:
            return todo
    raise HTTPException(status_code=404, detail="Todo not found")

@app.put("/todos/{id}", response_model=TodoItem)
def update_todo(id: int, done: bool):
    for todo in todos:
        if todo.id == id:
            todo.done = done
            return todo
    raise HTTPException(status_code=404, detail="Todo not found")

@app.delete("/todos/{id}", status_code=204)
def delete_todo(id: int):
    for idx, todo in enumerate(todos):
        if todo.id == id:
            todos.pop(idx)
            return
    raise HTTPException(status_code=404, detail="Todo not found")

📋 기능 요약

이처럼 Pydantic 모델을 중심으로 CRUD API를 설계하면 입력과 출력의 명세가 명확해지고,

자동 문서화 기능까지 덤으로 얻을 수 있습니다.

작은 실습이지만, API 설계의 기본을 익히기에 딱 좋은 구조입니다!

6. 실습을 통한 개념 정리 및 확장 방향 📚

지금까지 FastAPI에서 Pydantic을 활용한 데이터 모델링과 검증에 대해 배우고, 인메모리 Todo API 예제를 통해 실습까지 마쳤습니다.

단순히 동작하는 API를 만들었다는 것 이상의 의미가 있어요.

이번 학습을 통해 우리는 다음과 같은 핵심 역량을 갖추게 되었어요.

🎯 핵심 학습 내용 정리

• Pydantic의 BaseModel을 이용해 데이터 구조를 선언하고, 타입 검증과 기본값 설정까지 깔끔하게 처리하는 법을 익혔어요.
• 요청 바디에 Pydantic 모델을 활용해 JSON을 자동 파싱하고 오류를 422 상태 코드로 처리하는 구조를 경험했죠.
• response_model을 통해 응답 데이터를 명확히 통제하고, 민감 정보를 자동 제거하는 실전 팁도 확인했어요.
• Swagger 문서화에 입력/출력 모델이 자동 반영되는 과정을 통해 개발 생산성을 실감했습니다.

🔮 다음 단계: 확장 방향 제안

이제 실전 프로젝트나 포트폴리오 개발로 확장하고 싶다면, 아래 내용을 고려해보세요.

1. SQLite 또는 PostgreSQL 연동 – 실제 DB와 연동해 Todo를 저장하고 불러오는 구조로 확장하기
2. SQLAlchemy ORM 사용 – ORM 객체와 Pydantic 모델을 함께 사용하는 방법 학습하기
3. JWT 인증 추가 – 사용자 인증/인가 처리로 보안을 강화하기
4. 테스트 코드 작성 – pytest 등을 이용한 유닛 테스트 추가로 품질 보장

🌈 마무리하며

단순히 작동하는 코드보다 더 중요한 건, 데이터의 흐름을 안전하고 명확하게 만드는 것입니다.

Pydantic은 그 시작이자 가장 든든한 동반자예요.

앞으로 여러분의 FastAPI 프로젝트에 이 강력한 도구를 적극 활용해보세요.

마무리 ✍️

이번 글에서는 FastAPI에서 Pydantic을 활용한 데이터 모델링과 검증 방법을 처음부터 끝까지 실습 중심으로 정리해봤습니다.

처음 접할 땐 어렵게 느껴질 수 있지만, 막상 하나하나 따라 하다 보면 자동 유효성 검사, 직렬화, 문서화 등 정말 많은 일을 FastAPI가 알아서 해주는 걸 느끼게 될 거예요.

여기서 끝나지 않고, 이제는 진짜 서비스에 연결할 준비를 해보세요.

SQLite, PostgreSQL 같은 실제 데이터베이스 연동부터, JWT 인증 구현, SQLAlchemy ORM 적용, 서비스 배포 등 단계별로 확장할 수 있습니다.

중요한 건, 이 모든 기반에는 Pydantic 모델링이 있다는 점이에요.

혹시 오늘 처음 FastAPI를 써보신 분이라면, 분명 놀라셨을 거예요.

어떻게 이렇게 적은 코드로 API가 만들어지고, 검증까지 되는지.

앞으로는 더 다양한 프로젝트에서 Pydantic을 능숙하게 다루실 수 있을 겁니다. 👍

이제 여러분의 프로젝트에서 Pydantic을 자신 있게 활용해보세요.

복잡한 데이터 구조도 깔끔하게, 예외 처리도 자동으로, API 문서화까지 한 번에! 😎

파이썬 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() 함수를 활용해 경로 변수에 대해 더 정교한 검증을 할 수 있도록 지원해요.

예를 들어,

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

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

✅ 요약 정리

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처럼 사용자와 데이터를 주고받는 시스템의 기본이 되는 부분입니다.

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

FastAPI로 배우는 REST API 개발 입문

REST API, 아직도 어렵게 느껴지시나요?
FastAPI를 이용하면 믿을 수 없을 만큼 쉽게 웹 API를 만들 수 있어요!

안녕하세요!

오늘부터 여러분과 함께 Python의 강력한 웹 프레임워크 FastAPI를 활용한 REST API 개발을 단계별로 배워보려고 합니다.

요즘 웹 개발에 있어서 REST API는 기본 중의 기본이죠.

다양한 시스템이 서로 데이터를 주고받기 위해 가장 많이 사용되는 방식입니다.

특히 FastAPI는 빠르고 간편하며, 자동 문서화 기능까지 갖춰져 있어 초보자도 쉽게 API를 개발할 수 있는 환상적인 도구예요.

이 블로그 시리즈에서는 REST API의 개념부터 시작해서, FastAPI 설치, Hello World 예제, 엔드포인트 추가 실습까지 하나하나 직접 구현해보며 개념과 실습을 모두 챙길 거예요.

준비되셨나요?

그럼 첫 번째 이야기, REST API와 FastAPI의 만남을 시작해볼게요! 🚀

1. REST API란 무엇인가요? 🌐

REST API는 웹에서 데이터를 주고받는 가장 표준적인 방법 중 하나입니다.

먼저 이름부터 풀어볼까요?

REST는 Representational State Transfer의 약자인데요, 말이 좀 어렵게 느껴질 수 있지만 핵심은 간단합니다.

"웹 자원을 고유한 주소(URI)로 표현하고, 그 자원에 대해 HTTP 메서드를 통해 동작을 지정한다"는 게 핵심이에요.

우리가 평소에 웹 브라우저에서 주소창에 https://example.com/users를 입력하면 "users"라는 자원(데이터 목록)에 접근하는 거잖아요?

이처럼 REST에서는 각각의 자원을 URL을 통해 표현합니다.

그리고 어떤 동작을 하고 싶은지에 따라 GET, POST, PUT, DELETE 같은 HTTP 메서드를 사용해 요청을 보냅니다.

📌 REST 아키텍처의 6가지 원칙

• 클라이언트-서버 구조 : UI와 데이터 처리를 분리해 독립적으로 발전 가능
• 무상태성 (Stateless) : 서버는 요청을 받을 때 클라이언트의 상태를 기억하지 않음
• 캐시 처리 가능 : 클라이언트는 서버 응답을 캐싱해 효율성 향상 가능
• 계층화된 시스템 : 중간 서버를 통해 보안, 로드 밸런싱 등 기능 분리
• 인터페이스 일관성 : URI 설계와 메서드 사용이 일관되게 유지되어야 함
• 코드 온 디맨드(Optional) : 서버에서 클라이언트로 스크립트 등을 전달 가능

🧩 RESTful API 설계의 예시

이러한 설계 방식 덕분에 RESTful API는 명확하고 예측 가능하며 유지보수가 쉬운 구조를 가질 수 있어요.

그래서 요즘 거의 모든 서비스가 REST API 기반으로 구성되고 있죠.

그리고 이걸 Python으로 정말 쉽게 만들 수 있도록 도와주는 도구가 바로 FastAPI입니다.

2. RESTful API의 구조와 특징 🔍

RESTful API는 단순히 REST 원칙을 따르는 API 이상을 의미해요.

클라이언트와 서버 간의 소통을 효율적이고 일관되게 만들어주는 아키텍처 스타일이자 규칙의 집합이죠.

흔히들 “REST스럽다”는 표현을 쓰는데, 이는 API가 REST의 원칙을 잘 따르고 있다는 의미예요.

✅ RESTful API의 구조적 특징

1. URI를 통한 자원 표현 – 모든 자원은 고유한 URI로 식별됩니다. 예: /users, /posts/1
2. HTTP 메서드의 의미 명확화 – CRUD 작업을 각각 GET, POST, PUT, DELETE로 매핑합니다.
3. 무상태성(Stateless) – 요청은 독립적으로 처리되며, 서버는 이전 요청 상태를 저장하지 않습니다.
4. 표현(Representation)의 활용 – 클라이언트는 자원의 ‘표현’을 받으며, 보통은 JSON이나 XML 형식을 사용합니다.
5. 표준 HTTP 상태 코드 사용 – 예: 200(성공), 201(생성됨), 404(없음), 500(서버 오류)

💡 RESTful API가 주는 이점

RESTful API를 설계하면 얻게 되는 이점도 많아요.

가장 큰 장점은 바로 일관성과 가독성입니다.

예를 들어,

다음처럼 URI를 설계한다면 처음 보는 사람도 어떤 기능인지 대충 감이 올 거예요.

• GET /articles – 전체 글 목록 불러오기
• POST /articles – 새 글 작성
• GET /articles/3 – ID가 3인 글 조회

이처럼 RESTful한 API는 예측 가능하고 규칙 기반이기 때문에 협업 시에도 소통이 쉬워지고, 문서화를 따로 하지 않아도 사용할 수 있을 만큼 직관적인 경우도 많습니다.

❗REST API vs RESTful API – 혼동하지 마세요

간혹 REST API와 RESTful API를 같은 개념으로 쓰기도 하지만, 기술적으로는 살짝 차이가 있어요.

REST API는 단지 REST 기반 구조를 사용하는 API를 의미하고, RESTful API는 REST의 원칙을 충실히 따르는 ‘REST다운’ API를 말합니다.

즉, RESTful API는 REST API보다 좀 더 엄격한 규칙을 따른다는 뜻이에요.

RESTful한 구조를 유지하기 위해서는 불필요한 동사 사용을 피하고, 자원 중심으로 URI를 설계하며, HTTP 상태 코드도 적절히 활용해야 해요.

이런 기준을 지켜야만 “RESTful하다”고 말할 수 있답니다!

이제 RESTful API의 기본 철학과 구조에 대해 어느 정도 감이 오셨죠? 😉

다음 섹션에서는 FastAPI라는 도구를 통해 이런 RESTful API를 실제로 구현하는 방법을 배워볼 거예요.

기대되시죠?

3. FastAPI 프레임워크 소개 🚀

FastAPI는 최근 Python 웹 개발자들 사이에서 가장 주목받고 있는 비동기 기반 웹 프레임워크입니다.

Flask나 Django처럼 웹 애플리케이션을 만들 수 있으면서도,

비동기 처리, 자동 문서화, 타입 기반 유효성 검사 같은 최신 기능들을 기본으로 제공합니다.

📌 FastAPI의 핵심 특징

• 빠른 성능 – Starlette(ASGI 서버) 기반으로 구성되어 Node.js나 Go와 맞먹는 수준의 퍼포먼스를 자랑합니다.
• 타입 기반 유효성 검사 – Python의 타입 힌트를 활용해 Pydantic이 자동으로 데이터 검증 및 스키마 생성을 해줍니다.
• 자동 문서화 – OpenAPI(Swagger)와 ReDoc 기반 문서가 자동 생성되어 /docs나 /redoc 경로에서 API 테스트도 가능합니다.
• 비동기 처리 지원 – async/await 문법으로 고성능 API 서버 구현도 손쉽게 가능합니다.

⚙️ 왜 FastAPI인가요?

처음에는 Flask로도 충분하지 않나? 하는 생각이 들 수도 있어요. 저도 그랬거든요.

하지만 FastAPI를 사용해보면 정말 많은 차이를 느낄 수 있습니다.

특히 Swagger 문서 자동 생성과 비동기 처리 성능은 다른 프레임워크들이 따라오기 어려울 정도예요.

여기에 Python의 타입 힌트를 적극적으로 활용해, 코드 작성과 동시에 문서화와 유효성 검사를 자동으로 처리해주는 점이 초보자들에게도 큰 장점으로 작용합니다.

결론적으로 FastAPI는 빠르게 프로토타입을 만들고, 동시에 안정성과 문서화까지 챙기고 싶은 개발자에게 최적의 선택이에요.

Python을 이미 알고 있다면, FastAPI는 자연스럽고 직관적으로 배울 수 있습니다.

다음 글에서는 실제로 FastAPI를 설치하고 기본 개발 환경을 세팅하는 과정을 차근차근 안내해드릴게요.

이제 실습을 통해 본격적으로 시작해볼까요? 🔧

4. 개발 환경 설정과 FastAPI 설치 ⚙️

지금부터는 본격적으로 FastAPI를 개발 환경에 설치해보는 시간입니다.

FastAPI는 Python 3.7 이상에서 사용할 수 있기 때문에, 우선 Python 버전 확인부터 해볼게요.

그리고 가상환경을 만들어서 프로젝트별 의존성을 관리하는 것이 좋습니다.

🔍 Python 및 가상환경 설정

1. Python 버전 확인: python --version
2. 가상환경 생성: python -m venv venv
3. 가상환경 활성화
   • Windows: venv\Scripts\activate
   • Mac/Linux: source venv/bin/activate

가상환경이 활성화되면 프롬프트 앞에 (venv)가 붙어요.

이제 여기서 필요한 라이브러리를 설치하면 됩니다.

📦 FastAPI와 Uvicorn 설치

FastAPI는 자체적으로 웹 서버를 포함하고 있지 않기 때문에 ASGI 서버가 필요해요.

대부분의 개발자들은 Uvicorn을 사용합니다.

pip install fastapi
pip install "uvicorn[standard]"

[standard] 옵션을 포함하면 HTTP/2, WebSocket 등 다양한 기능도 함께 설치돼요.

설치가 끝나면 FastAPI 애플리케이션을 실행할 준비가 완료된 셈입니다.

📝 프로젝트 구조와 첫 파일 만들기

간단한 FastAPI 프로젝트 구조는 다음과 같아요:

• main.py – 앱 실행 파일
• venv/ – 가상환경 폴더

main.py 파일을 열고 FastAPI 기본 코드를 작성할 준비를 합니다.

다음 단계에서는 “Hello, FastAPI”라는 응답을 반환하는 아주 간단한 예제를 통해 첫 API를 직접 만들어볼 거예요.

지금까지 잘 따라오셨나요? 🧑‍💻

환경 설정만 마쳐도 절반은 완성된 셈입니다!

이제 직접 서버를 띄워보며 FastAPI가 어떻게 동작하는지 살펴보겠습니다.

5. Hello FastAPI - 첫 API 만들기 👋

드디어 우리가 기다리던 순간!

이제 FastAPI를 직접 실행해 보며 첫 번째 API를 만들어볼 거예요.

처음 만드는 만큼 아주 단순한 "Hello, FastAPI" 메시지를 반환하는 예제부터 시작해 보겠습니다.

📄 main.py 코드 작성

이제 main.py 파일을 열고

아래와 같이 코드를 작성해 주세요:

from fastapi import FastAPI

app = FastAPI()

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

이 코드에서 @app.get("/")는 루트 경로(/)에 GET 요청이 들어왔을 때 실행되는 함수입니다.

return 부분에서 반환하는 딕셔너리는 자동으로 JSON으로 변환돼서 응답으로 전송돼요.

🚀 서버 실행

이제 작성한 FastAPI 앱을 실행해볼게요.

터미널에 다음 명령어를 입력하세요:

uvicorn main:app --reload

main은 파일 이름, app은 FastAPI 객체입니다.

--reload 옵션을 붙이면 코드 변경 시 서버가 자동으로 재시작돼서 개발할 때 아주 편리하죠!

🔎 실행 결과 확인하기

• http://127.0.0.1:8000/ → {"message": "Hello, FastAPI"} 응답 확인
• http://127.0.0.1:8000/docs → Swagger 기반 API 문서 자동 생성
• http://127.0.0.1:8000/redoc → ReDoc 기반 문서 보기

정말 신기하지 않나요?

별도의 설정 없이도 이렇게 깔끔한 API 문서가 자동 생성됩니다. 🧙‍♂️

그리고 이게 FastAPI의 가장 큰 매력 중 하나예요. 작성한 API들을 테스트도 가능하니, 개발과 동시에 검증까지 가능하죠.

이제 FastAPI의 기본 구조와 실행 흐름을 이해하셨을 거예요.

다음 단계에서는 실제로 또 하나의 엔드포인트를 추가하면서 다양한 HTTP 메서드와 라우팅 개념도 함께 살펴보겠습니다.

6. 엔드포인트 추가 실습: 버전 정보 API 구현 🛠️

이전 단계에서 GET /으로 기본 응답을 반환하는 간단한 API를 만들어봤죠.

이번에는 FastAPI 앱에 새로운 엔드포인트를 하나 더 추가해보겠습니다.

예를 들어,

프로젝트의 버전 정보를 클라이언트에게 알려주는 API가 있다고 가정해볼게요.

📄 main.py에 엔드포인트 추가

@app.get("/version")
def get_version():
  return {"version": "0.1.0"}

이 함수는 /version 경로에 GET 요청이 들어왔을 때 버전 정보를 JSON 형식으로 반환합니다.

예를 들어,

클라이언트가 API의 버전 관리를 하고자 할 때 유용하게 사용할 수 있어요.

🔎 실행 후 테스트하기

• http://127.0.0.1:8000/version 에 접속하면 결과가 다음과 같이 나옵니다:
  {"version": "0.1.0"}
• Swagger UI 문서에서도 /version 경로가 자동으로 추가된 걸 확인할 수 있어요.

📌 엔드포인트를 추가하면서 익히는 FastAPI의 핵심

• 라우팅 – 경로(URL)마다 함수 하나씩 대응시켜 구조적으로 관리
• 함수 기반 뷰(View) – 각각의 엔드포인트는 Python 함수로 표현
• 자동 문서화 – 개발자가 문서를 별도로 작성하지 않아도 FastAPI가 Swagger 문서를 자동 생성

이번 실습을 통해 RESTful API의 핵심인 라우팅 설계를 직접 해보셨고, FastAPI가 얼마나 직관적이고 강력한지 직접 체험하셨을 거예요. 엔드포인트 추가는 이제 식은 죽 먹기죠?

점점 실전 API에 가까워지고 있죠? 😊

지금까지 우리는 REST API의 개념부터 FastAPI 설치, 기본 예제 구현까지 한 걸음씩 따라와 봤습니다.

처음에는 다소 낯설 수 있었던 REST 구조도, FastAPI의 직관적인 문법과 자동 문서화 덕분에 훨씬 더 쉽게 접근할 수 있었죠.

RESTful한 방식으로 API를 설계하면,

확장성과 유지보수성을 동시에 확보할 수 있다는 점에서 그 가치가 분명합니다.

FastAPI는 여기에 더해 빠른 속도, 간결한 코드, 뛰어난 생산성까지 갖추고 있어 Python 개발자라면 반드시 익혀야 할 도구예요.

다음 글에서는 POST 요청 처리와 입력 데이터 검증을 다룰 예정입니다.

본격적으로 사용자의 입력을 받아 처리하고, Pydantic을 활용한 스키마 기반 검증도 함께 배워볼 거예요.

기대되시죠? 😊

이 글이 도움이 되셨다면 댓글이나 공유도 환영합니다.

앞으로도 쉽고 실용적인 Python 백엔드 개발 이야기, 계속 함께해 주세요!