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

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

FastAPI로 REST API 만들기는 현대 웹 개발에서 필수적인 기술입니다. FastAPI는 Python 기반의 고성능 웹 프레임워크로, 빠른 개발 속도와 자동 문서화 기능을 제공합니다. 이 튜토리얼을 통해 여러분은 실제 프로덕션 환경에서 사용할 수 있는 REST API를 처음부터 끝까지 구축하는 방법을 배우게 됩니다. FastAPI의 핵심 기능인 타입 힌팅, 데이터 검증, 자동 API 문서 생성을 마스터하고, 실무에서 바로 활용할 수 있는 실전 예제를 통해 현업 개발자로 성장할 수 있습니다. 백엔드 개발자를 꿈꾸거나, 기존 Flask나 Django에서 FastAPI로 전환을 고려하는 개발자라면 이 가이드가 완벽한 출발점이 될 것입니다.

2. FastAPI 기본 개념 설명

FastAPI는 Starlette과 Pydantic을 기반으로 구축된 최신 Python 웹 프레임워크입니다. REST API는 Representational State Transfer의 약자로, HTTP 프로토콜을 통해 자원(Resource)을 주고받는 아키텍처 스타일입니다. FastAPI의 가장 큰 장점은 Python 3.6+의 타입 힌팅을 활용한 자동 데이터 검증과 OpenAPI(Swagger) 문서 자동 생성입니다.

주요 개념으로는 Path Operation(경로 작업)이 있습니다. 이는 HTTP 메서드(GET, POST, PUT, DELETE)와 URL 경로를 결합하여 API 엔드포인트를 정의하는 방식입니다. Pydantic 모델은 요청과 응답 데이터의 스키마를 정의하고 자동으로 검증합니다. Dependency Injection(의존성 주입)은 코드 재사용성을 높이고 데이터베이스 연결, 인증 등을 관리합니다.

FastAPI는 비동기 처리를 기본 지원하여 Node.js와 Go에 필적하는 성능을 제공합니다. async/await 문법을 사용해 높은 동시성을 처리할 수 있으며, 이는 대규모 트래픽을 다루는 서비스에 이상적입니다.

3. 단계별 구현 가이드

3.1 환경 설정 및 설치

먼저 Python 3.7 이상이 설치되어 있는지 확인합니다. 가상환경을 생성하고 FastAPI와 ASGI 서버인 uvicorn을 설치합니다:

# 가상환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# FastAPI 및 uvicorn 설치
pip install fastapi uvicorn[standard]

3.2 첫 번째 API 엔드포인트 생성

프로젝트 디렉토리에 main.py 파일을 생성하고 기본 구조를 작성합니다. FastAPI 인스턴스를 생성하고 간단한 GET 엔드포인트를 정의합니다. 데코레이터 패턴을 사용하여 HTTP 메서드와 경로를 지정하며, 함수는 JSON 형태로 자동 변환되는 딕셔너리나 Pydantic 모델을 반환합니다.

3.3 Pydantic 모델을 활용한 데이터 검증

API에서 데이터를 주고받을 때 타입 안정성과 검증이 중요합니다. Pydantic BaseModel을 상속받아 데이터 스키마를 정의합니다. 각 필드에 타입 힌팅을 추가하면 FastAPI가 자동으로 검증하고, 잘못된 데이터가 들어올 경우 명확한 에러 메시지를 반환합니다. Field 클래스를 사용하면 추가적인 검증 규칙(최소값, 최대값, 패턴 등)을 설정할 수 있습니다.

3.4 CRUD 작업 구현

실제 애플리케이션에서는 Create(생성), Read(조회), Update(수정), Delete(삭제) 작업이 필요합니다. 각 작업에 대응하는 HTTP 메서드를 사용합니다:

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

Path Parameter를 사용하여 특정 리소스를 식별하고, Query Parameter로 필터링 및 정렬 옵션을 제공합니다. Request Body에는 생성하거나 수정할 데이터를 담아 전송합니다.

3.5 상태 코드 및 예외 처리

적절한 HTTP 상태 코드 반환은 REST API의 핵심입니다. 200(성공), 201(생성됨), 404(찾을 수 없음), 422(검증 오류) 등을 상황에 맞게 사용합니다. HTTPException을 raise하여 에러를 처리하고, status_code와 detail 메시지를 제공합니다.

4. 실제 코드 예제와 설명

다음은 할 일(Todo) 관리 API의 완전한 예제입니다:

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

app = FastAPI(title="Todo API", version="1.0.0")

# Pydantic 모델 정의
class TodoBase(BaseModel):
    title: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=500)
    completed: bool = False

class TodoCreate(TodoBase):
    pass

class TodoResponse(TodoBase):
    id: int
    created_at: datetime
    
    class Config:
        orm_mode = True

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

# CREATE - 할 일 생성
@app.post("/todos/", response_model=TodoResponse, status_code=status.HTTP_201_CREATED)
async def create_todo(todo: TodoCreate):
    global todo_id_counter
    new_todo = {
        "id": todo_id_counter,
        "title": todo.title,
        "description": todo.description,
        "completed": todo.completed,
        "created_at": datetime.now()
    }
    todos_db.append(new_todo)
    todo_id_counter += 1
    return new_todo

# READ - 모든 할 일 조회
@app.get("/todos/", response_model=List[TodoResponse])
async def get_todos(skip: int = 0, limit: int = 10, completed: Optional[bool] = None):
    filtered_todos = todos_db
    if completed is not None:
        filtered_todos = [t for t in todos_db if t["completed"] == completed]
    return filtered_todos[skip : skip + limit]

# READ - 특정 할 일 조회
@app.get("/todos/{todo_id}", response_model=TodoResponse)
async def get_todo(todo_id: int):
    todo = next((t for t in todos_db if t["id"] == todo_id), None)
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todo

# UPDATE - 할 일 수정
@app.put("/todos/{todo_id}", response_model=TodoResponse)
async def update_todo(todo_id: int, todo_update: TodoCreate):
    todo = next((t for t in todos_db if t["id"] == todo_id), None)
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    
    todo["title"] = todo_update.title
    todo["description"] = todo_update.description
    todo["completed"] = todo_update.completed
    return todo

# DELETE - 할 일 삭제
@app.delete("/todos/{todo_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_todo(todo_id: int):
    global todos_db
    todo = next((t for t in todos_db if t["id"] == todo_id), None)
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    todos_db = [t for t in todos_db if t["id"] != todo_id]
    return None

이 코드는 완전한 CRUD 기능을 제공하며, Pydantic 모델을 통한 자동 검증, 적절한 HTTP 상태 코드, 에러 처리를 포함합니다. 서버를 실행하려면 uvicorn main:app --reload 명령어를 사용하고, http://localhost:8000/docs에서 자동 생성된 Swagger 문서를 확인할 수 있습니다.

5. 고급 활용 방법

데이터베이스 연동: SQLAlchemy와 함께 사용하여 실제 데이터베이스에 연결합니다. FastAPI는 ORM과의 통합이 매우 간편하며, async 데이터베이스 드라이버를 지원합니다.

인증 및 보안: OAuth2와 JWT를 활용한 토큰 기반 인증을 구현합니다. FastAPI의 Security 유틸리티를 사용하면 복잡한 인증 로직을 간결하게 작성할 수 있습니다. CORS 미들웨어를 추가하여 프론트엔드 애플리케이션과의 통신을 허용합니다.

미들웨어 및 백그라운드 태스크: 요청/응답 사이클에 로깅, 성능 모니터링을 추가하거나, BackgroundTasks를 사용하여 이메일 발송 등의 비동기 작업을 처리합니다.

테스트 작성: TestClient를 사용하여 API 엔드포인트를 테스트합니다. pytest와 결합하면 효율적인 테스트 자동화가 가능합니다.

배포: Docker 컨테이너화, Nginx 리버스 프록시 설정, AWS/GCP/Azure 클라우드 플랫폼에 배포하는 방법을 학습합니다.

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

FastAPI로 REST API 만들기는 이제 시작입니다. 이 튜토리얼에서 배운 기본기를 바탕으로 실제 프로젝트를 진행해보세요. 공식 문서(fastapi.tiangolo.com)는 상세한 가이드와 고급 기능을 제공합니다. GitHub에서 오픈소스 FastAPI 프로젝트를 분석하고, 커뮤니티에 참여하여 경험을 공유하세요. WebSocket, GraphQL 통합, 마이크로서비스 아키텍처 등 더 깊이 있는 주제로 나아가며 전문성을 키워나가시기 바랍니다. 꾸준한 실습과 프로젝트 경험이 진정한 실력을 만듭니다!