f:id:yoshiki_utakata:20190817135503p:plain

原文
Quickstart
Project Setup
Serializers
Views
URLs
Pagination
Settings
Testing our API

原文

Quickstart

ここでは、簡単なAPIを作成します。adminユーザーにだけユーザーとグループの閲覧と編集が可能なAPIを作成します。

Project Setup

tutorial という名前のDjango Projectを作成し、quickstartというアプリを作成します。

# プロジェクトのディレクトリを作成
mkdir tutorial
cd tutorial

# virtual environment を作成する
python3 -m venv env
source env/bin/activate  # On Windows use `env\Scripts\activate`

# Django と Django REST framework を作成する
pip install django
pip install djangorestframework

# プロジェクトとアプリケーションの設定をします
django-admin startproject tutorial .  # Note the trailing '.' character
cd tutorial
django-admin startapp quickstart
cd ..

プロジェクトのレイアウトはこのようになります。

$ 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

プロジェクトディレクトリの中にアプリケーションが作成されるのはちょっと違和感があるかもしれませんが、プロジェクトのnamespaceを切ることで、外部モジュールとの名前空間の衝突を回避できます。（これはquickstartの話から外れるので詳しくは説明しません）

アプリケーションを作成したら、データベースをマイグレーションします。

python manage.py migrate

admin というユーザーを作成します。パスワードは password123 とします。後にこのユーザーを認証に利用します。

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

これで準備は完了です。ここからは、アプリケーションのディレクトリを開いてコードを書いていきます。

Serializers

まず、Serializer を定義します。 tutorial/quickstart/serializers.py というモジュールを作成します。 Serializer はデータを「表示」するために使います。

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）をRDBの「関係」に使うかと思いますが、これを REST API で表現場合、ハイパーリンクを使います。

Views

次に 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):
    """
    API endpoint that allows users to be viewed or edited.
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer


class GroupViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows groups to be viewed or edited.
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

このように、共通の挙動を持つ部分は ViewSets と呼ばれるクラスでまとめるのが良いです。

こう書かずに、 function で完全別々に書くこともできますが、簡潔に書くよりも、 ViewSets を利用したほうがロジックが整理されるので良いです。

URLs

次は API の URL との紐付けを行いましょう。 tutorial/urls.py を開いてください。

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)

# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

ViewSets を使っているので、自動的にURL設定を生成することができます。 Route クラスを作成して登録するだけです。

もし、URLをカスタマイズしたい場合は、 class-based view を使えば、URLを明示的に指定することができます。

最後に、 Browsable API のログイン・ログアウトのためのルーティングを含めています。これは必須ではありませんが、APIに認証をつけたり、Browsable API を利用する場合は非常に便利です。

ページネーションとは、1ページにいくつのオブジェクトを返すか、を制御することです。ページネーションを有効にするには、 tutorial/settings.py に以下の行を追記します。

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

Settings

'rest_framework' を tutorial/settings.py の INSTALLED_APPS に追加してください。

INSTALLED_APPS = [
    ...
    'rest_framework',
]

これで準備ができました。

Testing our API

作ったAPIのをテストする準備ができました。下記コマンドでサーバーを動かしてみましょう。

python manage.py runserver

APIにアクセスできるようになったはずです。コマンドラインをつかってアクセスすることもできますし、curlを使ってもアクセスできます。

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/ にアクセスしてもよいです。

ブラウザから確認する場合は、右上のログインボタンからログインしてください。

簡単でしょう？

REST framework についてもっと深く理解したい場合は、上のメニューにある*1 API guide を見てください。

*1:公式のドキュメントは上部にメニューがあります

猫でもわかるWebプログラミングと副業

本業エンジニアリングマネージャー。副業Webエンジニア。Web開発のヒントや、副業、日常生活のことを書きます。

Quickstart - Django REST framework の簡単な日本語訳

原文