Django Rest Framework 3 훑어보기

Django Rest Framework 3을 이해해 보고자 튜토리얼 문서를 번역하고 있습니다. 의역이 난무하지만 기술적으로 잘못된 내용을 전달하지 않게 최선을 다해보겠습니다.

원문 - QuickStart Guide with Django Rest Framework3

번역을 허락해 준 Tom Christie에게 고마움을 전합니다.


훑어보기

이제부터 관리자 계정으로 사용자를 관리하는 간단한 API를 만들어 보겠습니다.

프로젝트 설정

tutorial이라는 이름으로 새로운 Django 프로젝트를 만든 다음 quickstart 앱을 생성합니다.

# 프로젝트용 디렉터리를 만듭니다
mkdir tutorial  
cd tutorial

# 패키지 환경을 독립적으로 관리하기 위해 가상 환경을 생성합니다
virtualenv env  
source env/bin/activate  # On Windows use `env\Scripts\activate`

# Django와 Django REST framework를 가상 환경에 설치합니다
pip install django  
pip install djangorestframework

# 프로젝트와 앱을 생성합니다
django-admin.py startproject tutorial .  # 마지막에 있는 .을 꼭 입력하세요  
cd tutorial  
django-admin.py startapp quickstart  
cd ..  

이제 처음으로 데이터베이스를 생성합니다.

python manage.py migrate  

관리자 계정으로 사용할 아이디와 비밀번호도 만들죠. 나중에 이 계정으로 인증을 할 겁니다.

python manage.py createsuperuser  

자, 이제 준비를 마쳤으니 코딩을 해봅시다.

시리얼라이저

시리얼라이저부터 만들어보죠. tutorial/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')


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

하이퍼링크 관계를 위해 HyperlinkedModelSerializer를 사용한 것을 눈여겨 보세요. 물론 주 키(primary key)나 다른 방법으로도 관계를 연결할 수 있겠지만, 하이퍼링크야말로 RESTful 디자인에 잘 어울립니다.

좋습니다. 이제 뷰를 만들죠. tutorial/quickstart/views.py 파일을 다음과 같이 작성합니다.

from django.contrib.auth.models import User, Group  
from rest_framework import viewsets  
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer


class UserViewSet(viewsets.ModelViewSet):  
    """
    사용자(user)를 보거나 편집하는 API
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer


class GroupViewSet(viewsets.ModelViewSet):  
    """
    그룹(group)을 보거나 편집하는 API
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

뷰를 여러 번 작성하기보다는 자주 사용되는 기능들을 묶은 ViewSet 클래스를 사용했습니다.

물론 필요에 따라 뷰를 잘게 나눌 수도 있습니다. 하지만 뷰셋(viewset)을 사용하면 뷰 로직을 아주 간결하고 체계적으로 유지할 수 있습니다.

문서의 제일 처음에 보여드렸던 클래스에서는 model 속성 대신 querysetserializer_class 속성을 사용했는데요.

일반적인 경우 ViewSet 클래스에 model 속성만 설정하면 serializerqueryset은 자동으로 설정됩니다. queryset이나 serializer_class 속성을 설정하면 API의 행동을 좀더 명시적으로 표현할 수 있는데 대다수 애플리케이션에서는 이렇게 하기를 권장합니다.

URL

자 이제 API URL을 연결해봅시다. tutorial/urls.py 파일입니다.

from django.conf.urls import url, include  
from rest_framework import routers  
from tutorial.quickstart import views

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

# 우리가 만든 API를 자동으로 라우팅합니다.
# 그리고 API 탐색을 위해 로그인 URL을 추가했습니다.
urlpatterns = [  
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

뷰 대신 뷰셋을 사용한 덕에, 뷰셋의 라우터(router) 클래스를 통해 API에 대한 URL이 자동으로 생성됩니다.

여기서도 역시, API URL을 여러분 마음대로 설정하고 싶다면 여러분이 직접 만든 클래스 기반 뷰(class based view)에 URL을 연결하면 되겠습니다.

마지막으로 탐색친화적(browseable)인 API를 만들기 위해 기본 로그인/로그아웃 뷰를 추가했습니다. 반드시 추가해야 하는 건 아니자만 여러분의 API가 인증 후 API 탐색을 허용하는 경우에는 유용하게 사용할 수 있겠습니다.

설정

전역 변수를 몇 개 설정해 봅시다. 페이지 기능을 켜고, API에는 관리자 계정만 접근하도록 합시다. tutorial/settings.py 파일에 다음 내용을 추가합니다.

INSTALLED_APPS = (  
    ...
    'rest_framework',
)

REST_FRAMEWORK = {  
    'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',),
    'PAGINATE_BY': 10
}

네, 이제 끝났습니다.


API 테스트하기

지금까지 만든 API를 테스트해 봅시다. 명령창에서 서버를 실행합니다.

python ./manage.py runserver  

이제 명령창에서 (curl 명령 등으로) API에 접근할 수 있습니다.

bash: curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/  
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/1/",
            "username": "admin"
        },
        {
            "email": "tom@example.com",
            "groups": [                ],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

httpie 같은 도구를 사용해도 좋습니다.

bash: http -a username:password http://127.0.0.1:8000/users/  
HTTP/1.1 200 OK  
...
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://localhost:8000/users/1/",
            "username": "paul"
        },
        {
            "email": "tom@example.com",
            "groups": [                ],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

아니면 웹 브라우저에서 봐도 되죠.

Quick start image

웹 브라우저를 사용한다면 오른쪽 상단의 버튼을 눌러 로그인을 해야 할 겁니다.

좋습니다. 쉽죠?

REST 프레임워크가 어떻게 작동하는지 더 알고 싶다면, 다음 튜토리얼을 계속 읽어가든지 API 가이드를 참고하세요.