[Django]Django REST Framework 튜토리얼 (Quickstart)

DRF를 사용해보기에 앞서 간단하게 API를 만들어볼 수 있는 DRF 공식 튜토리얼을 번역하면서 따라해볼 것이다.

학습하면서 진행하는 것이기에 해석에 오류가 있을 수 있다. 헷갈리는 부분은 아래의 공식 Documentation을 참고하자.

 

DRF Tutorial 공식 Documentation

---

Quickstart

우리는 관리자가 시스템에서 사용자와 그룹을 보고 편집할 수 있는 기능을하는 간단한 API를 만들 것이다.

 

Project setup

장고 프로젝트의 이름을 tutorial, app의 이름을 quick start로 생성하자.

# 프로젝트 디렉토리 생성
mkdir tutorial
cd tutorial

# 패키지 의존성을 독립적으로 사용하기 위한 파이썬 가상환경 생성
python3 -m venv env
source env/bin/activate  # 윈도우에서는 다음과 같이 사용 -> `env\Scripts\activate`

# 가상머신에 진입하여 django, djangorestframework 설치
pip install django
pip install djangorestframework

# django-admin으로 tutorial 이라는 장고 프로젝트를 시작함
django-admin startproject tutorial .  #  '.' 문자에 유의하자
cd tutorial
django-admin startapp quickstart
cd ..

 

프로젝트의 layout은 다음과 같이 구성되어 있다.

$ pwd
<some path>/tutorial
$ find .
.
./manage.py
./tutorial
./tutorial/__init__.py
./tutorial/quickstart
./tutorial/quickstart/__init__.py
./tutorial/quickstart/admin.py
./tutorial/quickstart/apps.py
./tutorial/quickstart/migrations
./tutorial/quickstart/migrations/__init__.py
./tutorial/quickstart/models.py
./tutorial/quickstart/tests.py
./tutorial/quickstart/views.py
./tutorial/settings.py
./tutorial/urls.py
./tutorial/wsgi.py

application이 프로젝트 디렉토리내에 생성된 것이 비정상적으로 보일 수 있다. 프로젝트의 namespace를 사용하면 외부 모듈과의 이름 충돌을 방지할 수 있다.

 

이제 첫번째로 할 것은 데이터베이스의 싱크를 맞추는 작업이다.

python manage.py migrate

우리는 또한 admin이라고 불리는 initial 유저를 password123이라는 비밀번호와 함께 생성할 것이다. 우리는 뒷부분에 나오는 예제에서 해당 사용자를 통해 인증할 수 있다.

python manage.py createsuperuser --email admin@example.com --username admin

데이터베이스를 설정하고 초기 사용자가 생성되고 사용할 준비가 되면 앱의 디렉토리를 열고 코딩을 시작하면 된다.

 

Serializers

첫 번째로 우리는 몇개의 serializer를 선언할 것이다. 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와 함께 hyperlinked 관계를 사용하고 있다. 너는 기본키 및 다양한 기타 관계들을 사용할 수도 있지만 hyperlinking은 좋은 RESTful 디자인이다.

 

Views

좋다, 우리는 이제 view를 작성할 것이다. tutorial/quickstart/views.py를 열어 아래와 같이 입력하자.

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


class UserViewSet(viewsets.ModelViewSet):
    """
    사용자를 보거나 편집할 수 있는 API endpoint
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]


class GroupViewSet(viewsets.ModelViewSet):
    """
    사용자를 보거나 편집할 수 있는 API endpoint
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer
    permission_classes = [permissions.IsAuthenticated]

여러가지의 뷰를 작성하는 대신 모든 일반적인 동작을 ViewSets라는 클래스로 그룹화 할 수 있다.

우리는 필요한 경우에 이를 개별 뷰로 쉽게 나눌 수 있지만, viewsets를 사용하면 뷰 로직이 매우 간결하게 된다. (잘 구성되어 있다)

 

URLs

좋다, 이제 tutorial/urls.py에 API URLs를 연결해 볼 것이다.

from django.urls import include, path
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)

# 자동 URL 라우팅을 사용하여 API를 연결한다.
# 또한 검색 가능한 API에 대한 로그인 URL을 포함한다.
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

왜냐하면 우리는 view 대신 viewset을 사용하기 때문에 router 클래스에 viewset을 등록하기만 하면 API에 대한 URL conf를 자동으로 생성할 수 있다.

다시 말해, API URL에 대한 더 많은 제어가 필요한 경우라면 regular class-based views를 사용하고, URL conf 를 명시적으로 작성하기만 하면 된다.

마지막으로, 우리는 탐색 가능한 API와 함께 기본 로그인 및 로그아웃 view를 포함하고 있다. 이것은 선택사항이지만 API에 인증이 필요하고 탐색가능한 API 사용하려는 경우에 유용하다. 

 

Pagination

페이지네이션을 사용하면 페이지 당 반환되는 object 수를 제어할 수 있다. 이를 활성화 하려면 tutorial/settings.py에 아래와 같은 내용을 추가하면 된다.

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

 

Settings

이제 tutorial/settings.py에 INSTALLED_APPS 부분에 'rest_framework'를 추가하자. 

INSTALLED_APPS = [
    ...
    'rest_framework',
]

 

모두 끝이 났다.

---

Testing our API

이제 우리는 우리가 만든 API를 테스트할 준비가 되었다. 다음 명령을 통해 서버를 실행시키자.

python manage.py runserver

우리는 이제 curl과 같은 도구를 사용하여 command-line에서 API에 엑세스 할 수 있다.

bash: curl -H 'Accept: application/json; indent=4' -u admin:password123 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 admin:password123 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"
        }
    ]
}

혹은 브라우저를 통해 http://127.0.0.1:8000/users/에 접속하여 직접 값을 넣을수도 있다.

만약 브라우저를 통해 값을 넣고 싶은 경우에는 오른쪽 상단 모서리에 있는 컨트롤을 활용하여 admin 게정으로 로그인해야 한다.

(아까 옵션으로 permission_classes = [permissions.IsAuthenticated]를 주었기 때문이다)

 

REST frameworkd가 어떻게 결합되는지 더 깊이 이해하려면 the tutorial로 이동하거나, API guide를 찾아보아라.

 

DRF 공식 Documentation에 있는 Quick start 튜토리얼에 대한 번역을 진행해보았습니다. 
다음번에는 Serialization 튜토리얼을 따라하면서 번역해볼 예정입니다.