[DRF] Tutorial + Quickstart: 첫 API 서버 5분

DRF quickstart, DRF tutorial, 첫 REST API, DRF 시작, django rest framework tutorial

정의

Django REST Framework (DRF) 를 처음 사용 하는 사람을 위한 순차 시작 가이드. 5분 안에 동작하는 API 서버 완성.

DRF 개요는 django-rest-framework. Django 기본은 django-tutorial.

DRF는 무엇인가

한 줄로: Django 위에 REST API 를 짜기 위한 배터리 포함 라이브러리.

Django 자체는 웹앱 (HTML 페이지) 을 잘 만들지만, JSON API 는 손이 많이 간다. DRF 는 그 반복을 자동화한 사실상 표준 도구.

목적

없을 때 (순수 Django)	DRF 사용 시
Model → dict 수동 변환	Serializer 자동
Body JSON 파싱 수동	request.data 자동
CRUD view 6개 손으로	ModelViewSet 한 줄
URL 매핑 손으로	Router.register() 한 줄
인증 코드 수동	authentication_classes 선언만
API 문서 손으로	drf-spectacular 자동

대안 비교

flowchart TB
    Q{Django에서 REST API}
    Q --> Plain["순수 Django (JsonResponse)"]
    Q --> DRF["Django REST Framework"]
    Q --> Ninja["Django Ninja"]
    Q --> FastAPI["FastAPI (별개 프레임워크)"]
    Plain --> P1["직렬화 수동, 검증 수동, 문서화 없음"]
    DRF --> D1["Serializer, ViewSet, Router 자동, OpenAPI 자동"]
    Ninja --> N1["FastAPI 스타일 (type hint), Django ORM 그대로"]
    FastAPI --> F1["가장 빠름, Django ORM은 별도 통합 필요"]

옵션	장점	단점	언제?
DRF	성숙, 커뮤니티 최대, 문서/책 많음	학습 곡선, 클래스 계층 복잡	Django 프로젝트에 REST API 얹을 때 기본 선택
Django Ninja	빠름, FastAPI 스타일, 코드 간결	상대적으로 신생, 라이브러리 생태계 작음	작은 Django 프로젝트, type hint 선호
FastAPI	가장 빠름, 비동기 우선, 타입 안전	Django ORM 통합 별도, ecosystem 다름	Django 종속성 없을 때
Plain Django	학습 곡선 낮음, 의존성 없음	매번 boilerplate 반복	endpoint 1-2개 짜리 프로토타입

DRF 는 대규모 Django 프로젝트의 REST API 표준. 새 프로젝트에 REST 필요 → DRF 기본 선택.

요청이 어떻게 흐르는가 (한눈에)

DRF는 다음 파이프라인으로 매 요청을 처리한다. 이 순서 를 알면 후속 페이지 이해가 쉽다.

각 스테이지 상세:

단계	하는 일	다음 페이지
1. URL Router	path 매칭 후 View 선택	drf-routers
2. Authentication	Authorization 헤더 읽고 request.user 세팅	drf-authentication
3. Permission	이 user 가 이 view 접근 가능?	django-drf-permissions
4. Throttle	이 user 너무 자주 요청? (429)	drf-pagination-throttling
5. View	실제 비즈니스 로직	drf-views, django-drf-viewset
6. Serializer	Model ↔ dict 변환, 검증	django-drf-serializers
7. Renderer	Accept 헤더 보고 JSON/HTML 등 선택	drf-request-response

요구사항 (2026)

• Django 4.2, 5.x, 6.0
• Python 3.10-3.14

설치

pip install djangorestframework
pip install markdown           # Browsable API 마크다운
pip install django-filter      # 필터링

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    ...,
    'rest_framework',           # ← 추가
    'rest_framework.authtoken', # Token auth 쓸 때
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
}

Quickstart: User API (5분 완성)

1. Serializer (Model → JSON)

# quickstart/serializers.py
from django.contrib.auth.models import User, Group
from rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'groups', 'is_staff']

class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ['url', 'name']

자세한 건 django-drf-serializers.

2. ViewSet (Endpoint)

# quickstart/views.py
from django.contrib.auth.models import User, Group
from rest_framework import viewsets, permissions
from .serializers import UserSerializer, GroupSerializer

class UserViewSet(viewsets.ModelViewSet):
    """전체 CRUD 자동!"""
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]

class GroupViewSet(viewsets.ModelViewSet):
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

자세한 건 django-drf-viewset.

3. Router (URL 자동)

# urls.py
from django.urls import path, include
from rest_framework import routers
from quickstart.views import UserViewSet, GroupViewSet

router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
router.register(r'groups', GroupViewSet)

urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
]

자세한 건 drf-routers.

4. 실행

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

브라우저에서 http://127.0.0.1:8000/ 접속 → Browsable API 자동 렌더링!

Browsable API

flowchart LR
    Browser -->|Accept: text/html| DRF
    DRF -->|HTML rendering| Browsable[Browsable API<br/>인터랙티브 UI]
    Browser -->|Accept: application/json| DRF
    DRF -->|JSON| JSON[JSON 응답]

API 호출 예시

# 목록 조회
curl -H 'Accept: application/json' http://127.0.0.1:8000/users/

# 생성 (session auth)
curl -X POST http://127.0.0.1:8000/users/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -u admin:admin \
  -d '{"username": "koa", "email": "koa@example.com", "groups": []}'

# 상세
curl http://127.0.0.1:8000/users/1/

# 삭제
curl -X DELETE http://127.0.0.1:8000/users/1/ -u admin:admin

Tutorial 순서 (권장 학습)

flowchart LR
    S["1. Quickstart<br/>(이 페이지)"] --> Ser["2. Serialization<br/>(drf-serializers)"]
    Ser --> RR["3. Requests/Responses<br/>(drf-request-response)"]
    RR --> CBV["4. Class-based views<br/>(drf-views)"]
    CBV --> Auth["5. Auth + Permissions<br/>(drf-authentication, drf-permissions)"]
    Auth --> Rel["6. Relationships<br/>(nested serializers)"]
    Rel --> VS["7. ViewSets + Routers<br/>(drf-viewset, drf-routers)"]

FBV vs APIView vs GenericView vs ViewSet

flowchart TD
    Q{복잡도 vs 자유도}
    Q -->|"최대 자유도"| FBV["@api_view (FBV)"]
    Q -->|"OO + 자유"| APIView["APIView (CBV)"]
    Q -->|"CRUD 반복"| Gen["Generic Views (ListAPIView 등)"]
    Q -->|"완전 자동 CRUD"| VS["ViewSet + Router"]

각 4개 스타일:

# 1. FBV
@api_view(['GET', 'POST'])
def user_list(request):
    if request.method == 'POST':
        serializer = UserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data, status=201)
    users = User.objects.all()
    return Response(UserSerializer(users, many=True).data)

# 2. APIView
class UserList(APIView):
    def get(self, request):
        users = User.objects.all()
        return Response(UserSerializer(users, many=True).data)

# 3. Generic Views
class UserList(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# 4. ViewSet
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

다음 학습 순서

이 튜토리얼 후 순서:

1. django-drf-serializers - Serializer 심화
2. drf-request-response - Request/Response 객체
3. drf-views - Views 종류
4. drf-authentication - 인증
5. django-drf-permissions - 권한
6. drf-pagination-throttling - Pagination + Rate limit
7. drf-filtering - 필터링
8. django-drf-viewset - ViewSet 심화
9. drf-routers - Router 심화
10. drf-schemas-openapi - OpenAPI 문서화
11. drf-testing - 테스트

다른 프레임워크 비교

Framework	Serializer	Auto CRUD	Browsable API
DRF	Serializer	ViewSet	예
FastAPI	Pydantic	없음	Swagger UI
Django Ninja	Pydantic	없음	Swagger UI
Rails	Active Model Serializers	Scaffold	없음
Spring Boot	Jackson	Spring Data REST	없음
NestJS	class-validator	없음	Swagger 통합

흔한 함정

관련 위키

• django-rest-framework (개요)
• django-drf-serializers
• django-drf-viewset
• django-drf-permissions
• django-tutorial (Django 기본)