FastAPI로 REST API 만들기 – 초보자도 쉽게 따라하는 완벽 가이드

1. 도입 – 학습 목표 및 필요성

FastAPI로 REST API 만들기는 현대 웹 개발에서 필수적인 기술입니다. FastAPI는 Python 기반의 고성능 웹 프레임워크로, 빠른 개발 속도와 자동 문서화 기능을 제공합니다. 이 튜토리얼에서는 FastAPI의 기본 개념부터 실전 프로젝트까지 단계별로 학습하며, REST API 설계 원칙과 구현 방법을 완벽하게 마스터할 수 있습니다. 백엔드 개발자를 꿈꾸는 초보자부터 실무 개발자까지 모두에게 유용한 가이드가 될 것입니다. 특히 타입 힌팅을 활용한 자동 검증과 Swagger UI를 통한 API 문서 자동 생성은 개발 생산성을 극대화시켜줍니다.

2. 기본 개념 설명

FastAPI란?
FastAPI는 Starlette와 Pydantic을 기반으로 만들어진 최신 Python 웹 프레임워크입니다. Node.js나 Go에 필적하는 높은 성능을 자랑하며, Python 3.6+ 타입 힌팅을 적극 활용합니다.

REST API 핵심 개념
REST(Representational State Transfer)는 HTTP 프로토콜을 활용한 아키텍처 스타일입니다. 주요 HTTP 메서드로는 GET(조회), POST(생성), PUT(전체 수정), PATCH(부분 수정), DELETE(삭제)가 있습니다.

FastAPI의 주요 특징

• 빠른 성능: ASGI 서버를 사용하여 비동기 처리 지원
• 자동 문서화: Swagger UI와 ReDoc 자동 생성
• 타입 안정성: Pydantic을 통한 데이터 검증
• 직관적인 코드: 데코레이터 기반의 간결한 문법
• 생산성: 적은 코드로 많은 기능 구현

3. 단계별 구현 가이드

3-1. 개발 환경 설정

Step 1: Python 설치 확인
Python 3.7 이상이 필요합니다. 터미널에서 버전을 확인하세요.

python --version

Step 2: 가상환경 생성
프로젝트별 독립적인 환경을 만들어 패키지 충돌을 방지합니다.

python -m venv fastapi_env
source fastapi_env/bin/activate  # Windows: fastapi_env\Scripts\activate

Step 3: FastAPI 및 Uvicorn 설치
FastAPI와 ASGI 서버인 Uvicorn을 설치합니다.

pip install fastapi uvicorn[standard]

3-2. 첫 번째 API 만들기

Step 1: 프로젝트 구조 생성

mkdir fastapi_project
cd fastapi_project
touch main.py

Step 2: 기본 라우트 작성
main.py 파일에 첫 번째 엔드포인트를 작성합니다. 루트 경로(‘/’)에 접근하면 환영 메시지를 반환하는 간단한 API입니다.

Step 3: 서버 실행
Uvicorn을 사용하여 개발 서버를 실행합니다. –reload 옵션은 코드 변경 시 자동으로 서버를 재시작합니다.

uvicorn main:app --reload

Step 4: API 테스트
브라우저에서 http://127.0.0.1:8000 접속하거나, http://127.0.0.1:8000/docs 에서 자동 생성된 Swagger UI 문서를 확인할 수 있습니다.

3-3. 데이터 모델 정의

Pydantic 모델 활용
Pydantic을 사용하면 타입 안정성과 자동 검증을 동시에 얻을 수 있습니다. BaseModel을 상속받아 데이터 스키마를 정의합니다.

3-4. CRUD 작업 구현

Create (생성): POST 메서드로 새 리소스 생성
Read (조회): GET 메서드로 리소스 조회
Update (수정): PUT/PATCH 메서드로 리소스 수정
Delete (삭제): DELETE 메서드로 리소스 삭제

각 작업은 적절한 HTTP 상태 코드를 반환해야 합니다. 예를 들어 생성 성공 시 201, 조회 성공 시 200, 삭제 성공 시 204를 반환합니다.

4. 실제 코드 예제와 설명

FastAPI로 REST API 만들기의 핵심은 명확한 데이터 모델과 직관적인 라우팅입니다. 다음은 실전에서 사용할 수 있는 완전한 예제입니다.

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime

app = FastAPI(title="할일 관리 API", version="1.0.0")

# 데이터 모델 정의
class TodoBase(BaseModel):
    title: str = Field(..., min_length=1, max_length=100, description="할일 제목")
    description: Optional[str] = Field(None, max_length=500, description="상세 설명")
    completed: bool = Field(False, description="완료 여부")

class TodoCreate(TodoBase):
    pass

class TodoResponse(TodoBase):
    id: int
    created_at: datetime
    
    class Config:
        json_schema_extra = {
            "example": {
                "id": 1,
                "title": "FastAPI 학습하기",
                "description": "튜토리얼 완료하기",
                "completed": False,
                "created_at": "2025-11-24T10:00:00"
            }
        }

# 임시 데이터 저장소
todos_db = []
todo_id_counter = 1

# API 엔드포인트
@app.post("/todos", response_model=TodoResponse, status_code=status.HTTP_201_CREATED)
async def create_todo(todo: TodoCreate):
    """새로운 할일 생성"""
    global todo_id_counter
    todo_dict = todo.model_dump()
    todo_dict["id"] = todo_id_counter
    todo_dict["created_at"] = datetime.now()
    todos_db.append(todo_dict)
    todo_id_counter += 1
    return todo_dict

@app.get("/todos", response_model=List[TodoResponse])
async def get_todos(skip: int = 0, limit: int = 10):
    """할일 목록 조회 (페이지네이션)"""
    return todos_db[skip:skip + limit]

@app.get("/todos/{todo_id}", response_model=TodoResponse)
async def get_todo(todo_id: int):
    """특정 할일 조회"""
    for todo in todos_db:
        if todo["id"] == todo_id:
            return todo
    raise HTTPException(status_code=404, detail="할일을 찾을 수 없습니다")

@app.put("/todos/{todo_id}", response_model=TodoResponse)
async def update_todo(todo_id: int, todo_update: TodoCreate):
    """할일 수정"""
    for index, todo in enumerate(todos_db):
        if todo["id"] == todo_id:
            updated_todo = todo_update.model_dump()
            updated_todo["id"] = todo_id
            updated_todo["created_at"] = todo["created_at"]
            todos_db[index] = updated_todo
            return updated_todo
    raise HTTPException(status_code=404, detail="할일을 찾을 수 없습니다")

@app.delete("/todos/{todo_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_todo(todo_id: int):
    """할일 삭제"""
    for index, todo in enumerate(todos_db):
        if todo["id"] == todo_id:
            todos_db.pop(index)
            return
    raise HTTPException(status_code=404, detail="할일을 찾을 수 없습니다")

코드 설명:

• Pydantic 모델: Field를 사용해 검증 규칙 정의
• 응답 모델: response_model로 자동 직렬화 및 문서화
• 상태 코드: 적절한 HTTP 상태 코드 반환
• 예외 처리: HTTPException으로 에러 처리
• 쿼리 파라미터: skip과 limit으로 페이지네이션 구현

5. 고급 활용 방법

5-1. 데이터베이스 연동

SQLAlchemy와 함께 사용하여 실제 데이터베이스에 연결할 수 있습니다.

pip install sqlalchemy databases[postgresql]

5-2. 인증 및 보안

OAuth2, JWT 토큰을 활용한 인증 시스템을 구현할 수 있습니다. FastAPI는 보안 관련 유틸리티를 기본 제공합니다.

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

5-3. 미들웨어 추가

CORS 설정, 로깅, 요청 처리 시간 측정 등을 미들웨어로 구현합니다.

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

5-4. 비동기 처리

async/await를 활용하여 높은 동시성을 처리할 수 있습니다. 데이터베이스 쿼리나 외부 API 호출 시 특히 유용합니다.

5-5. 테스팅

TestClient를 사용하여 API를 테스트할 수 있습니다.

from fastapi.testclient import TestClient

client = TestClient(app)

def test_create_todo():
    response = client.post("/todos", json={"title": "테스트"})
    assert response.status_code == 201

6. 마무리 및 추가 학습 자료

이 튜토리얼을 통해 FastAPI로 REST API 만들기의 핵심 개념과 실전 구현 방법을 배웠습니다. FastAPI는 배우기 쉽고 강력한 기능을 제공하여 빠른 개발이 가능합니다.

추가 학습 자료:

• 공식 문서: https://fastapi.tiangolo.com – 한국어 번역 지원
• FastAPI GitHub: 실제 예제 코드와 이슈 확인
• Pydantic 문서: 데이터 검증 심화 학습
• SQLAlchemy 튜토리얼: 데이터베이스 연동 심화
• 실전 프로젝트: 블로그 API, 쇼핑몰 API 만들기에 도전해보세요

FastAPI로 REST API 만들기를 마스터하면 현대적인 웹 애플리케이션 백엔드를 효율적으로 개발할 수 있습니다. 지금 바로 실습을 시작하고, 여러분만의 API를 만들어보세요!