[파이썬]FastAPI로 초간단 REST API 서버 만들기 – 실습 중심

Python으로 API를 만들고 싶은데 Django는 무겁고 Flask는 너무 기본적이라 고민이신가요? FastAPI는 빠르고 현대적인 Python 기반 웹 프레임워크로, 문법은 간결하지만 성능은 Node.js급입니다.

이번 포스트에서는 FastAPI를 이용해 누구나 따라할 수 있는 간단한 REST API 서버를 직접 만들어보며, 실무에서도 바로 활용 가능한 구조와 코드를 제공합니다. Python 3.11 기반이며 VSCode + uvicorn + pydantic 등을 실전 위주로 활용합니다.

📌 바로가기 목차

1. FastAPI란? 2. 개발환경 세팅 (Python + VSCode) 3. Hello FastAPI – 첫 API 만들기 4. CRUD API 실습 (POST, GET, PUT, DELETE) 5. 자주 묻는 질문 (FAQ) 6. 실무를 위한 베스트 프랙티스 & 요약

FastAPI로 쉽고 빠르게 REST API 서버를 구축하는 방법을 소개하는 프리미엄 블로그 커버

 

1. FastAPI란?

FastAPI는 Python 기반의 최신 웹 프레임워크로, 빠른 성능과 자동 문서화, 비동기 지원 등 다양한 장점을 갖춘 API 전용 프레임워크입니다. 타입 힌트 기반으로 Pydantic을 활용해 데이터 유효성 검사를 자동으로 수행하고, Swagger(OpenAPI)를 통해 API 문서를 자동 생성합니다.

Flask보다 간결하고 Django보다 가볍지만 강력한 기능을 제공하며, 특히 async/await 기반의 비동기 처리를 자연스럽게 지원하여 고성능 API 서버 개발에 적합합니다.

Starlette와 Pydantic을 내부적으로 활용하고 있어, 배우기 쉽고 생산성 높은 구조를 가지고 있으며, 빠르게 배우고 빠르게 배포할 수 있는 점이 실무에서도 큰 장점으로 작용합니다.

2. 개발환경 세팅 (Python + VSCode)

FastAPI는 Python 3.7 이상에서 동작하지만, 최신 버전인 Python 3.10+ 사용을 권장합니다. 아래는 VSCode 기반의 로컬 개발 환경을 설정하는 단계입니다.

1. Python 설치 확인: python --version 또는 python3 --version
2. 가상환경 생성: python -m venv venv
3. 가상환경 활성화:
   • Windows: venv\\Scripts\\activate
   • Mac/Linux: source venv/bin/activate
4. 필수 패키지 설치: pip install fastapi uvicorn
5. VSCode 확장 추천: Python, Pylance, REST Client

💡 설치 확인

$ pip list

Package    Version
---------- -------
fastapi    0.109.0
uvicorn    0.25.0

📂 프로젝트 구조 예시

📁 fastapi-app/
├── main.py
├── venv/
└── requirements.txt

여기까지 설정했다면 main.py를 생성하고 서버를 띄울 준비가 된 것입니다. 다음 단계에서는 첫 API를 만들어보겠습니다.

3. Hello FastAPI – 첫 API 만들기

이제 main.py 파일을 생성하고 가장 기본적인 API 서버를 만들어 봅니다. FastAPI는 타입 힌트와 데코레이터를 기반으로 동작하며, 문법은 매우 직관적입니다.

📄 main.py

from fastapi import FastAPI

app = FastAPI()

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

@app.get(\"/hello/{name}\")
def say_hello(name: str):
    return {\"greeting\": f\"안녕하세요, {name}님!\"}

🚀 서버 실행

$ uvicorn main:app --reload

• http://127.0.0.1:8000/ → { \"message\": \"Hello FastAPI!\" }
• http://127.0.0.1:8000/hello/jun → { \"greeting\": \"안녕하세요, jun님!\" }

✨ 자동 문서화 (Swagger)

FastAPI는 /docs URL로 자동 API 문서(Swagger UI)를 제공합니다. 브라우저에서 http://127.0.0.1:8000/docs 에 접속해보세요.

4. CRUD API 실습 (POST, GET, PUT, DELETE)

FastAPI에서는 RESTful 방식의 API를 매우 간단하게 작성할 수 있습니다. 아래는 사용자 정보를 관리하는 CRUD API의 예제입니다. 내부 DB는 없고, 리스트에 데이터를 저장해 실습을 진행합니다.

📦 main.py – 전체 코드

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

fake_db: List[User] = []

@app.post(\"/users\", status_code=201)
def create_user(user: User):
    fake_db.append(user)
    return user

@app.get(\"/users\", response_model=List[User])
def read_users():
    return fake_db

@app.get(\"/users/{user_id}\")
def read_user(user_id: int):
    for user in fake_db:
        if user.id == user_id:
            return user
    raise HTTPException(status_code=404, detail=\"User not found\")

@app.put(\"/users/{user_id}\")
def update_user(user_id: int, updated_user: User):
    for i, user in enumerate(fake_db):
        if user.id == user_id:
            fake_db[i] = updated_user
            return updated_user
    raise HTTPException(status_code=404, detail=\"User not found\")

@app.delete(\"/users/{user_id}\")
def delete_user(user_id: int):
    for i, user in enumerate(fake_db):
        if user.id == user_id:
            del fake_db[i]
            return {\"result\": \"User deleted\"}
    raise HTTPException(status_code=404, detail=\"User not found\")

쉽게 배우는 REST API 서버 – FastAPI 강의형 썸네일 이미지

 

🔍 테스트 URL

• POST /users → 사용자 생성
• GET /users → 모든 사용자 목록 조회
• GET /users/1 → ID로 단일 사용자 조회
• PUT /users/1 → 사용자 정보 수정
• DELETE /users/1 → 사용자 삭제

이제 Swagger UI를 통해 테스트해 보세요: http://127.0.0.1:8000/docs

5. 자주 묻는 질문 (FAQ)

Q FastAPI는 Flask보다 어떤 점이 더 좋나요?

FastAPI는 타입 힌트를 기반으로 자동 입력 검증 및 Swagger 문서 생성을 제공하며, Flask보다 비동기 성능과 구조적 유지보수 측면에서 우수합니다.

Q FastAPI는 Django보다 더 좋은 선택인가요?

Django는 올인원 프레임워크로 Admin, ORM 등이 강점이지만, FastAPI는 빠른 API 구축과 가벼운 서비스에 더 적합합니다. 프로젝트 성격에 따라 선택하세요.

Q FastAPI에서 DB 연결은 어떻게 하나요?

SQLAlchemy, Tortoise ORM 등 다양한 라이브러리와 연동할 수 있으며, 비동기 또는 동기 방식 선택이 가능합니다. 세션 및 Dependency Injection도 지원됩니다.

 

Q 배포는 어떻게 하나요? uvicorn만 사용하면 되나요?

개발 중에는 uvicorn --reload로 충분하지만, 실운영 환경에선 Gunicorn+Uvicorn 조합 또는 Docker, Nginx Reverse Proxy를 함께 사용하는 것이 일반적입니다.

Q 로그인 기능이나 JWT 인증은 구현이 어려운가요?

fastapi.security 모듈을 활용하면 OAuth2PasswordBearer, JWT 기반 인증을 쉽게 구현할 수 있습니다. 로그인 엔드포인트, 토큰 발급, 인증 데코레이터로 구성하세요.

6. 실무를 위한 베스트 프랙티스 & 요약

FastAPI는 빠르고 생산성이 높지만, 실무에서는 보안과 구조화 측면에서 몇 가지 중요한 점을 신경 써야 합니다. 다음은 실무 개발자를 위한 팁입니다.

• Pydantic 모델을 통해 입력 검증을 철저히 하세요.
• HTTPException으로 예외 처리를 명확히 구조화하세요.
• Swagger 문서는 실제 API와 동기화되므로 유지 보수가 쉽습니다.
• 서비스 구조 분리 (예: Router, Service, Repository)를 고려하세요.
• 비동기(async def) 사용을 고려하면 성능 최적화가 가능합니다.

📌 마무리 요약

• FastAPI는 문법이 간결하면서도 자동 문서화와 타입 안정성이 뛰어납니다.
• 가벼운 프로젝트나 마이크로서비스에 특히 적합합니다.
• RESTful API를 처음부터 끝까지 짜는 데 걸리는 시간도 매우 짧습니다.
• Python 개발자라면 반드시 경험해볼 만한 프레임워크입니다.

이번 포스트가 도움이 되셨다면 댓글 또는 구독으로 소통해 주세요. 실무 적용 사례나 궁금한 점은 언제든 환영합니다!