Python Django REST API 개발 - 실무 완전 가이드 | Backend

2026년 6월 업데이트

Django 5.2 LTS(2027년까지 지원)와 DRF 3.16 기준으로 전면 점검했다. Python 3.13/3.14 호환, 비동기(async) 뷰 활용, 그리고 Django Ninja라는 대안까지 2026년 현재 상황에 맞춰 내용을 갱신했다.

개요 및 중요성

Django REST Framework(DRF)는 Python으로 REST API를 만들 때 10년 넘게 사실상 표준 자리를 지켜 온 라이브러리다. 2026년 현재도 가장 널리 배포된 Django API 계층이며, ViewSet과 라우터, 권한(Permission) 시스템은 대규모 서비스에서 충분히 검증됐다. 채용 시장의 거의 모든 Django 개발자가 DRF를 안다는 점도 무시할 수 없는 강점이다.

기준 환경은 Django 5.2 LTS다. 5.2는 장기 지원(LTS) 릴리스로 최소 3년간(2027년 4월 이후까지) 보안 업데이트를 받는다. 이전 LTS인 4.2의 지원은 2026년 4월에 종료됐으므로, 새 프로젝트는 물론 운영 중인 서비스도 5.2로 올려두는 것이 안전하다. DRF는 3.16이 안정 버전이며 Python 3.10 이상을 요구하고, Python 3.13을 권장 버전으로 본다.

이 글은 프로젝트 셋업부터 직렬화(Serializer), 인증, 비동기 처리, 배포 직전 점검까지 실무에서 바로 쓰는 흐름으로 정리했다. 각 단계는 복붙이 아니라 "왜 이렇게 쓰는가"를 함께 다룬다.

                    bash
# Django 5.2 LTS + DRF 3.16 환경 구성 (Python 3.13 권장)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install "Django>=5.2,<5.3" "djangorestframework>=3.16"

django-admin startproject config .
python manage.py startapp api

TIP

버전을 Django>=5.2,<5.3처럼 마이너 단위로 고정하면, 의도치 않은 메이저 업그레이드로 인한 호환성 깨짐을 막을 수 있다. pip freeze > requirements.txt로 잠금 파일도 함께 관리하자.

핵심 개념과 기본 원리

DRF의 흐름은 단순하다. 요청이 들어오면 Serializer가 JSON을 검증하고 모델 객체로 변환하며, View(ViewSet)가 권한과 비즈니스 로직을 처리하고, Router가 URL을 자동으로 묶어 준다. 이 세 가지만 이해하면 대부분의 CRUD API는 금방 만든다.

가장 먼저 손에 익혀야 할 것은 ModelSerializer다. 모델 필드를 그대로 노출하지 말고, fields를 명시적으로 지정해 필요한 필드만 드러내는 습관이 중요하다. 비밀번호나 내부 식별자 같은 필드가 실수로 응답에 섞이는 사고를 막아 준다.

                    python
# api/serializers.py
from rest_framework import serializers
from .models import Article

class ArticleSerializer(serializers.ModelSerializer):
    class Meta:
        model = Article
        fields = ["id", "title", "body", "created_at"]  # 필요한 필드만 명시
        read_only_fields = ["id", "created_at"]

자주 하는 실수

fields = "__all__"는 편하지만 모델에 민감한 필드가 추가될 때 그대로 노출된다. 운영 코드에서는 필드를 명시적으로 나열하는 쪽을 기본값으로 삼는 게 안전하다.

실전 구현 가이드

ViewSet과 Router를 쓰면 목록 조회, 단건 조회, 생성, 수정, 삭제를 한 클래스로 처리하고 URL까지 자동으로 연결된다. 직접 URL을 일일이 쓰는 것보다 유지보수가 훨씬 쉽다.

                    python
# api/views.py
from rest_framework import viewsets, permissions
from .models import Article
from .serializers import ArticleSerializer

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all().order_by("-created_at")
    serializer_class = ArticleSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]

# config/urls.py
from rest_framework.routers import DefaultRouter
from api.views import ArticleViewSet

router = DefaultRouter()
router.register("articles", ArticleViewSet)
urlpatterns = router.urls

인증은 2026년에도 토큰 기반이 표준이다. 세션 인증은 같은 도메인 웹 프런트에 적합하고, 모바일이나 외부 클라이언트에는 JWT를 많이 쓴다. JWT는 djangorestframework-simplejwt로 짧은 액세스 토큰 + 갱신 토큰 조합을 권장한다. Django 5.1부터 도입된 LoginRequiredMiddleware도 DRF 3.16과 함께 쓸 수 있게 정리됐다.

TIP

액세스 토큰 유효기간은 짧게(예: 5~15분), 갱신 토큰은 길게 두고 회전(rotation) 정책을 켜 두면 토큰 탈취 시 피해 범위를 줄일 수 있다.

고급 패턴 및 최적화

가장 흔한 성능 함정은 N+1 쿼리다. 목록을 직렬화할 때 연관 객체를 건건이 조회하면 쿼리 수가 폭증한다. select_related(정방향 외래키)와 prefetch_related(역방향·다대다)를 queryset에 걸어 한 번에 가져오는 것이 기본이다. 페이지네이션도 처음부터 켜 두자 — 전체 목록을 한 번에 내려보내는 API는 데이터가 쌓이면 그대로 장애가 된다.

                    python
# N+1 방지 + 페이지네이션
class ArticleViewSet(viewsets.ModelViewSet):
    queryset = (
        Article.objects.select_related("author")
        .prefetch_related("tags")
        .order_by("-created_at")
    )
    serializer_class = ArticleSerializer
    pagination_class = None  # settings의 DEFAULT_PAGINATION_CLASS 사용 권장

2026년의 변화는 비동기(async)다. Django 5.2는 비동기 ORM 커넥션 풀링을 기본 지원하고, 초기 비동기 구현에서 발목을 잡던 sync-to-async 전환 비용을 상당 부분 없앴다. DRF 자체는 여전히 동기 기반이지만, 외부 API 호출이나 파일 업로드처럼 I/O가 많은 작업은 async 뷰로 감싸고 ORM 호출은 sync_to_async로 처리하는 식으로 이득을 볼 수 있다. 순수 비동기 DRF가 필요하면 adrf(Async Django REST framework) 패키지를 검토하면 된다.

또 하나 주목할 흐름은 Python 3.14의 프리스레드(free-threaded, no-GIL) 빌드다. 3.13에서 실험적으로 들어온 GIL 제거 빌드가 3.14에서 정식 지원 구성으로 승격됐고, 단일 스레드 성능 손해도 3.13의 약 40%에서 10~15% 수준으로 줄었다. CPU 바운드 백그라운드 작업에서는 멀티코어 병렬 처리로 실질 이득이 보고된다. 다만 기본값은 아니며 호환성 함정이 있으니, 운영 도입은 충분한 벤치마크 이후에 결정하는 게 맞다.

DRF 대신 Django Ninja?

2026년 Django API 생태계는 사실상 두 갈래다. DRF는 생태계 깊이와 안정성에서, Django Ninja는 async-우선 설계·Pydantic v2 검증·자동 OpenAPI 문서·FastAPI식 개발 경험에서 앞선다. Ninja는 Python 3.13·3.14도 지원한다. 새 프로젝트라면 Ninja가 매력적인 기본값이지만, 이미 잘 돌아가는 DRF 코드베이스라면 굳이 마이그레이션할 이유는 없다. 안정성과 생태계가 그 자체로 자산이기 때문이다.

마무리

정리하면, 2026년의 표준 조합은 Django 5.2 LTS + DRF 3.16 + Python 3.13이다. Serializer로 입력을 검증하고, ViewSet과 Router로 CRUD를 묶고, JWT로 인증을 처리하고, select_related/페이지네이션으로 성능을 챙기는 흐름만 손에 익혀도 실무급 API의 8할은 끝난다.

여기서 한 걸음 더 나가고 싶다면 I/O 작업의 비동기화, Python 3.14 프리스레드 빌드 검토, 그리고 새 프로젝트에서의 Django Ninja 도입을 순서대로 살펴보자. 작은 CRUD부터 만들어 보고, 인증과 최적화를 하나씩 붙여 나가는 방식이 가장 빠른 학습 경로다.