Function view

お気付きの通り、一番簡単な View は Response を返却する関数型のビューということになります。

最小のビューは第一仮引数に request を受取るように定義するだけです。 URLにパラメータを埋め込む場合は引数を増やしたりします。この辺は Django と同じですね。

from rest_framework.response import Response
from rest_framework.decorators import api_view

@api_view(['GET', 'POST'])
def hello_world(request):
    if request.method == 'POST':
        return Response({"message": "Got some data!", "data": request.data})
    return Response({"message": "Hello, world!"})

書き方はよくあるDjangoのビューと同じですね。 違うのは api_view というデコレータの有無です。 これを使うことにより、 DRF の設定がビューに引き継がれるようになります。

また 引数 として HTTP メソッド を文字列として指定できます。 この辺は require_http_methods と同じですね。

ちなみに後述するクラス型のビューにはパーミッションやパーサなど複数の設定項目があるのですが、関数型のビューには同じようにデコレータを使って設定することになります。

本当に単純な機能は関数ベースで書いたほうが逆に可読性がよく保守しやすいかもしれません。 設定項目が増えてきたら見栄えが悪いので後述するクラスベースにしちゃったほうがいいです。

Class based view

クラスベースのビューは HTTP メソッドごとの インスタンスメソッドを定義できます。 まさにこれは Django の View の様な感じですね。 まぁ実際に継承してるんですが

また、他にも後述する様々な設定を追加できます。 これは関数だとデコレータで連ねて書く必要があり可読性が悪くなってしまうのでクラスベースビューのメリットであると言えそうです。

クラスベース ビュー は APIView クラスを継承して定義します。 対象のHTTPメソッドがそのまま インスタンスメソッド になります。 DRF 的には ハンドラメソッド と呼ばれるようで、 後述する アクションメソッド とは区別します。

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import authentication, permissions
from django.contrib.auth.models import User

class UserNameAPI(APIView):
    authentication_classes = (authentication.TokenAuthentication,)
    permission_classes = (permissions.IsAdminUser,)

    def get(self, request, format=None):
        usernames = [user.username for user in User.objects.all()]
        return Response(usernames)

    def post(self, request):
        # 普通こんなことはしないが..
        users = [User(username=name) for name in request.POST.getlist('name')]
        User.objects.bulk_create(users)
        return Response({'succeeded': True})

特定のモデルに紐付かないような処理は クラスベースで記述するのがおすすめと言えるでしょう。 私は、クエリが複雑すぎて queryset じゃ処理しきれないとかで SQLAlchemy で処理した結果を返したい という場合などに APIView を使っています。

ちなみに ジェネリックビュークラス(後述) は この APIView を継承して定義されています。

リファレンス

http://www.django-rest-framework.org/api-guide/views/

Generic view

Django や Django REST framework のお作法に従うなら便利で、そして種類も多い View です。

このビューはモデルというか クエリセット にひも付くため簡略化した書き方ができるのが特徴です。 場合によっては処理を書かなくてよいことが多々あります。

と思ってリファレンスを見ると種類がめっちゃ多いことに気づきますが、 作成, 一覧, 取得, 削除, 更新 の用途によって使い分ければよいだけの話なので身構えることはありません。

Generic Viewクラスは 特定のレコードに 紐づくか, 紐付かないか で分類されています。

紐付かない

• CreateAPIView (作成)
• ListAPIView (一覧)
  • ListCreateAPIView (作成, 一覧)

紐づく

• RetrieveAPIView (取得)
  • RetrieveUpdateAPIView (取得, 更新)
  • RetrieveDestroyAPIView (取得, 削除)
    • RetrieveUpdateDestroyAPIView (取得, 更新, 削除)
• DestroyAPIView (削除)
• UpdateAPIView (更新)

手始めに ListAPIView を使ってみましょう。

from rest_framework import generics

class UserList(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

これだけでユーザ一覧を返却するAPIビューの出来上がりです。 各ユーザレコードは UserSerializer に従ってシリアライズされます。

(シリアライザの説明は Serializer の 使い方 をまとめてみた を参照ください。

内部的な話をすると、ジェネリックビューは クエリセット と密接に結びついた GenericAPIView という基底クラスと、 クエリセット を使ってレスポンスを組み立てるための Mixin クラス を継承して定義されています。

Mixin は レスポンスを返却するためのインスタンスメソッドを ハンドラメソッドとは別の名前で提供しており、これを アクションメソッドと呼ぶそうです。

ジェネリックビューでは ハンドラメソッドから呼び出される形で実行されます。

以下のように対応しています。

リファレンスには明記されていなかったんですが、 処理を変えたいときは多分アクションメソッドをオーバーライドすることになるんじゃないかな。 確証はないです。

リファレンス

http://www.django-rest-framework.org/api-guide/generic-views/

ViewSets

ビューセットは 取得, 一覧, 登録, 更新, 削除 をまとめて管理するビューです。 (取得と一覧だけできる ReadOnlyModelViewSet というのもあります)

当たり前の処理は 自分で書かなくても この ViewSet が肩代わりしてくれます。

from rest_framework import viewsets

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

一つ前に書いた UserList の名前と継承クラスを変えただけです。 これだけで、このビューは 取得, 一覧, 登録, 更新, 削除 ができるようになりました。

ViewSet は ハンドラメソッドでなく アクションメソッドで定義するべきと記述がありました。

ジェネリックビューとの一番の違いはおそらく、 アクション にあると思います。

action デコレータ を使ってインスタンスメソッドを定義することで、パスに機能を追加できます。

説明が難しいですが、百聞は一見にしかずということで以下のように ViewSet を定義することで

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    pagination_class = MyCursorPagination

    @action(methods=['get'], detail=False)
    def fullnames(self, request):
        return Response([
            '{user.first_name} {user.last_name}'.format(user=user)
            for user in self.get_queryset()
        ])

    @action(methods=['get'], detail=True)
    def fullname(self, request, pk=None):
        user = self.get_object()
        return Response('{user.first_name} {user.last_name}'.format(user=user))

# Router については後述
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
urlpatterns = [url(r'^api/', include(router.urls))]

インスタンスメソッド名で URL にアクセスすることで 任意の 処理が実行できます。

$ curl -X GET 'http://127.0.0.1:8000/api/users/fullnames/'
["takayuki shimizukawa","takanory suzuki","teruhiko teruya"]
$ curl -X GET 'http://127.0.0.1:8000/api/users/1/fullname/'
"takayuki shimizukawa"
$ curl -X GET 'http://127.0.0.1:8000/api/users/2/fullname/'
"takanory suzuki"
$ curl -X GET 'http://127.0.0.1:8000/api/users/3/fullname/'
"teruhiko teruya"

• methods は 登録対象の HTTP メソッド
• detail は 詳細API or 一覧API
  • True の場合は pk 引数が必要

これめっちゃ便利ですね。これは検証してないけど Router で登録したときしか使えないのかな。

リファレンス

http://www.django-rest-framework.org/api-guide/viewsets/

個人的に考えた使い分けとしては

• クエリセットを使わない API は クラスベースビュー(APIView) か 関数ビュー
• モデルに対する処理をまとめて一つのクラスで定義したい場合は View set
• それ以外は Generic view

みたいな感じかなぁ。

from django.conf.urls import url, include

urlpatterns = [
  url(r'^hello/$', hello_world),
  url(r'^user/$', UserList.as_view()),
]

BasicAuthentication

DRFが提供する最も単純な認証です。Basic認証と同じように ユーザとパスワード(をBASE64エンコードしたもの) を毎回送信することでユーザの認証をします。

たとえば、ユーザの認証情報が test1 / test だとすると、これらを BASE64 化した dGVzdDE6dGVzdA== を Authentication ヘッダに渡せば認証できます。

$ curl -X GET http://127.0.0.1:8000/check/ -H 'Authorization: Basic dGVzdDE6dGVzdA=='
{"user":"test1","auth":"None"}

復号が容易なためセキュリティ的にはあまり推奨できません。 ローカルでの動作確認など閉ざされた目的でのみ利用するようにしてください。

SessionAuthentication

SessionAuthentication は従来の Django と同じ認証方法、つまり Cookie による認証です。

簡易的にセッションを発行するためのビューを以下のように定義します。

class SessionView(APIView):
    def get(self, request):
        # 本来は認証しよう
        # user = authenticate(request.query_params['username'], request.query_params['password'])
        user = User.objects.get(username=request.GET['username'])
        r = login(request, user)
        return Response({'session': request.session.session_key})

urlpatterns += [url(r'^session/', SessionView.as_view())]

アクセスするとセッションIDが得られます。

$ curl -X GET http://127.0.0.1:8000/session/?username=test1
{"session":"a55jor0z61vzhk8n0t2z71vz2rgyleg1"}

発行された Session ID (Set-Cookieされたものと同じ) を Cookie ヘッダに渡すと

$ curl -X GET http://127.0.0.1:8000/check/ -H 'Cookie: sessionid=a55jor0z61vzhk8n0t2z71vz2rgyleg1;'
{"user":"test1","auth":"None"}

認証できましたね。

TokenAuthentication

TokenAuthentication は DRF が提供する認証で SessionAuthentication に少し似ていますが、Cookie は使いません。

利用するためには settings.py を編集し、

INSTALLED_APPS = (
    # :
    'rest_framework.authtoken',
)

トークンを管理するためのテーブル用のマイグレーションをする必要があります。

スキーマはこんな感じになってます。 user_id で一意制約がついてるので、ユーザに対して一つしか発行できません。

sqlite> .schema authtoken_token
CREATE TABLE IF NOT EXISTS "authtoken_token" (
  "key" varchar(40) NOT NULL PRIMARY KEY,
  "created" datetime NOT NULL,
  "user_id" integer NOT NULL UNIQUE REFERENCES "auth_user" ("id") DEFERRABLE INITIALLY DEFERRED
);

例えば トークンを発行するためのビューを以下のように定義します。

class TokenView(APIView):
    def get(self, request):
        # 本来は認証しよう
        # user = authenticate(request.query_params['username'], request.query_params['password'])
        user = User.objects.get(username=request.GET['username'])
        token, _ = Token.objects.get_or_create(user=user)
        return Response({'token': str(token)})

urlpatterns += [url(r'^token/', TokenView.as_view())]

ユーザ名を指定してトークンを得て、

$ curl -X GET http://127.0.0.1:8000/token/?username=test2
{"token":"38a7db568458feb9f8d6008805bba3fca7e1ca00"}

Authorization ヘッダに トークンを指定すると

$ curl -X GET http://127.0.0.1:8000/check/ -H 'Authorization: Token 38a7db568458feb9f8d6008805bba3fca7e1ca00'
{"user":"test2","auth":"38a7db568458feb9f8d6008805bba3fca7e1ca00"}

認証できました。

Basic Authentication や Session Authentication では None だった auth に値が入っています。 トークン認証の場合は Token モデルのインスタンスが格納されるようです。何に使えるかはよくわからない。

コマンドラインからやる場合は、 drf_create_token を使います。すでに有効なトークンがある場合はそれが返却される模様です。

$ ./manage.py drf_create_token test1
Generated token d2f2eacba404528ff49dd6c998bd02fc0a9b3069 for user test1
# 再生成は -r をつける
$ ./manage.py drf_create_token -r test1
Generated token b87175b965cf7d886173fff45eb9cab790d2ae6d for user test1

トークン認証の特徴はドメインに紐付かないことにあります。

先に説明した２つの認証は認証情報がドメインにひも付き、自動的に送信されるという特性がありました。 これは便利な半面 CSRF という攻撃を受けるリスクを孕んでいます。トークンの場合はクライアント側で明示的に指定されない限り認証情報が送信されないため、CSRFの心配はありません。

また、Cookieと違いドメインの制約がないため外部ドメインに対するリクエストであっても認証情報を渡せます。

画面ごとに クラスを指定するのが面倒な場合、settings.py の REST_FRAMEWORK['DEFAULT_AUTHENTICATION_CLASSES'] 対して Authentication クラスのモジュールパスを指定します。

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework.authentication.BasicAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ),
}

CustomAuthentication

自分で Authentication クラスを作る場合は Authentication 関連クラスを継承して、認証処理を authenticate メソッドに記述します。

今回は TokenAuthentication クラスを継承して トークン認証に有効期限を設けてみます。

class ExpirationTokenAuthentication(TokenAuthentication):
    delta = timedelta(seconds=TIMEOUT_SECONDS)

    def authenticate_credentials(self, key):
        try:
            token = Token.objects.get(key=key)
        except Token.DoesNotExist:
            raise exceptions.AuthenticationFailed("Invalid Token.")

        if not token.user.is_active:
            raise exceptions.AuthenticationFailed("User is not active.")

        now = timezone.now()
        if now - token.created > self.delta:
            token.delete()
            raise exceptions.AuthenticationFailed("The Token is expired.")

        token.created = now
        token.save(update_fields=['created'])
        return (token.user, token)

参考: How to Override TokenAuthentication Backend to Detect an Expiring Token

60秒で有効期限が切れるなんてネットバンクも真っ青なセキュリティですね。

from datetime import timedelta

from django.utils import timezone
from django.core.cache import cache
from rest_framework.authentication import TokenAuthentication
from rest_framework.authtoken.models import Token
from rest_framework import exceptions

TIMEOUT_SECONDS = 60


class ExpirationTokenAuthentication(TokenAuthentication):
    delta = timedelta(seconds=TIMEOUT_SECONDS)

    def authenticate_credentials(self, key):
        try:
            token = Token.objects.get(key=key)
        except Token.DoesNotExist:
            raise exceptions.AuthenticationFailed("Invalid Token.")

        if not token.user.is_active:
            raise exceptions.AuthenticationFailed("User is not active.")

        now = timezone.now()
        if now - (cache.get(key) or token.created) > self.delta:
            token.delete()
            raise exceptions.AuthenticationFailed("The Token is expired.")

        cache.set(key, now, TIMEOUT_SECONDS)
        return (token.user, token)

リファレンス

http://www.django-rest-framework.org/api-guide/authentication/

PageNumberPagination

ページ番号によってページネーションをする最も一般的なクラスです。上記の例もこれですね。

操作できるパラメータは以下です。

レスポンスのページネーションは以下の情報を含みます。

ページサイズが 1 の ページネーションを設定してみます。

class MyPagination(pagination.PageNumberPagination):
    page_size = 1


class UserListView(generics.ListAPIView):
    pagination_class = MyPagination
    serializer_class = UserSerializer
    queryset = User.objects.filter()

# 1ページ目
$ curl -X GET 'http://127.0.0.1:8000/user/'
{"count":3,"next":"http://127.0.0.1:8000/user/?page=2","previous":null,"results":[{"id":1,"username":"test1"}]}
# 2ページ目
$ curl -X GET 'http://127.0.0.1:8000/user/?page=2'
{"count":3,"next":"http://127.0.0.1:8000/user/?page=3","previous":"http://127.0.0.1:8000/user/","results":[{"id":2,"username":"test2"}]}
# 3ページ目
$ curl -X GET 'http://127.0.0.1:8000/user/?page=3'
{"count":3,"next":null,"previous":"http://127.0.0.1:8000/user/?page=2","results":[{"id":3,"username":"test3"}]}
# 4ページ目(存在せず)
$ curl -X GET 'http://127.0.0.1:8000/user/?page=4'
{"detail":"Invalid page."}

LimitOffsetPagination

レコードを切り出す位置を指定するページングするクラスです。 DBとの limit, offset にそのまま渡して利用できるので柔軟なページングが実現できます。

レスポンスの形式は PageNumberPagination と同じです。

CursorPagination

これは 前後 へのページ移動だけを許可するクラスです。 上で紹介した2つのクラスと違い、特定のページ番号に直接アクセスする手段を与えません。

ということなんですが、実はBase64エンコードしたパラメータを cursor に与えることで表示位置を特定しているようです。

例えば /api/users/?cursor=cj0xJnA9Mw%3D%3D というURLであれば、 r=1&p=3 のというパラメータが指定されます。 encode_cursor のソースコード を見る限りでは以下のようなパラメータになっているようです。 (意味については詳しく調べてません

ちなみに、このページネーションはデフォルトで created フィールドでソートするため、 User のように存在しないモデルに対してこのページネーションを使うと以下のようなエラーになります。

なので、大抵は次のように継承し、別のソート条件を指定して使うことになると思います。

class MyCursorPagination(CursorPagination):
    ordering = ('id', )

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    pagination_class = MyCursorPagination

ordering の指定によりレコードの順番が完全に保証できる場合、 レコードが途中で増えたとしても検索結果がずれて同じレコードが表示されるということが発生しません。

そのため、頻繁に追加されるレコードをリアルタイムで一覧するようなページに適しています。

これが CursorPagination のメリットだそうです。

備考

通常、ページングというのは SQLでは LIMIT 句と OFFSET 句によって実現されますが、 DBの内部では OFFSET で指定された行数より前のレコードも取り出されているので、 遡れば遡るほど OFFSET の数値が大きくなりページングは重くなっていきます。

IDのような一意かつ大小関係を持つ列をもとにWHERE句で絞ってから 表示するというのが１つの解決策のようで、 CursorPagination はまさにそれの実装ですね。

失敗から学ぶRDBの正しい歩き方 Software Design plus

アンチパターンをうまないためのノウハウがケース付きで紹介されています。この話は 6.2章に書いてあります。読みやすいのでオススメ。

BasePagination

カスタマイズ用のページネーションクラスです。

この処理は 上記のクラスとは違い実際に処理を書く必要が出てきます。

具体的には paginate_queryset(self, queryset, request, view=None) と get_paginated_response(self, data) を上書きします。

カスタマイズした ページネーションクラス は pagination_class クラス変数 として View クラス に指定します。ここは解説しません。

リファレンス

http://www.django-rest-framework.org/api-guide/pagination/

ソースコード

https://github.com/encode/django-rest-framework/blob/3.8.2/rest_framework/pagination.py