Django REST frameworkチュートリアル2:リクエストと応答

チュートリアル索引
Django REST frameworkのシリーズチュートリアルは、チュートリアルのインデックスディレクトリをクリックすることができます.
これからは、REST frameworkのコア部分に本格的に触れていきます.もちろん、私たちはまずいくつかの重要な基本要素を認識する必要があります.
リクエストオブジェクト(Request object)
REST frameworkは、通常のRequestから継承されるHttpRequestオブジェクトを導入したが、受信したリクエストをより柔軟に解析することができる.Requestオブジェクトのコア機能は、その中のrequest.dataプロパティです.この属性はrequest.POSTと似ていますが、私たちのWeb APIにとって、より役に立ちます.

request.POST  #       (form)  ，    “POST”  .
request.data  #       .    'POST', 'PUT'   'PATCH'  .

レスポンスオブジェクト(Response object)
REST frameworkは、Responseオブジェクトを同時に導入し、純粋なコンテンツを携帯し、コンテンツ交渉(Content Negotiation)によって、どのような形でクライアントに戻るかを決定するTemplateResponseである.

return Response(data)  #         ，   ，       .

ステータスコード(Status codes)
あなたのビューでは、純粋な数字のステータスコードを使用すると、コードの読み取りに不利で、ステータスコードを書き間違えても、簡単に気づくことはありません.REST frameworkは、HTTP_400_BAD_REQUESTモジュール内のstatusなどのステータスコードごとにより明確な識別を提供する.私たちはあちこちで、このような識別子を使って、純粋な数字のステータスコードではなく、これは良い考えです.
パッケージAPIビュー(wrapping API views)
REST frameworkは、API viewを記述する2つのパッケージを提供します.

使用@api_view装飾器、方法に基づくビュー

継承APIViewクラス、クラスベースのビュー

これらのビューはカプセル化され、いくつかの機能を提供しています.例えば、あなたのビューがRequestインスタンスを受信できることを確認します.また、Responseオブジェクトにコンテンツを付与し、コンテンツネゴシエーションが正常に動作するようにする.
ビューパッケージには、エラーリクエストに遭遇したときに自動的に405 Method Not Allowedに応答するなどの動作も内蔵されています.request.dataを処理する場合、入力されたフォーマットが不適切であるために発生するParseError異常(exception)は、ビューパッケージで処理されます.
すべての要素を結合
次に、これらの新しい要素でいくつかのビューを書き続けましょう.
私たちはview.pyファイルの中でJSONResponseクラスを必要としないので、削除してください.そして、私たちは少し、微細な再構築を始めることができます.

from rest_framework import status
from rest_framework.decorators import api_view
from rest_framework.response import Response
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer


@api_view(['GET', 'POST'])
def snippet_list(request):
    """
             （snippets），          （snippet）
    """
    if request.method == 'GET':
        snippets = Snippet.objects.all()
        serializer = SnippetSerializer(snippets, many=True)
        return Response(serializer.data)

    elif request.method == 'POST':
        serializer = SnippetSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

現在の例は、以前の例に比べて改善されています.それは、簡潔になり、Forms APIを使用したことがある場合は、非常によく知られていることがわかります.ネーミング式のステータスコードも使用しており、応答のステータスを読みやすくしています.
次は、views.pyモジュールにあるsnippetの詳細ビューです.

@api_view(['GET', 'PUT', 'DELETE'])
def snippet_detail(request, pk):
    """
      ,                 （snippet instance）。
    """
    try:
        snippet = Snippet.objects.get(pk=pk)
    except Snippet.DoesNotExist:
        return Response(status=status.HTTP_404_NOT_FOUND)

    if request.method == 'GET':
        serializer = SnippetSerializer(snippet)
        return Response(serializer.data)

    elif request.method == 'PUT':
        serializer = SnippetSerializer(snippet, data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

    elif request.method == 'DELETE':
        snippet.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

これまでは、一般的なDjangoビューとあまり変わらないことをよく知っていたはずです.
なお、ビュー内のRequest/Responseのコンテンツタイプを解析/定義することは明確ではありません.request.dataは入力されたjsonリクエストを自分で処理します.もちろん、別のフォーマットも処理できます.同様に、応答オブジェクトとデータを返すだけで、REST frameworkは応答内容、レンダリング(render)を正しいフォーマットにすることができます.
我々のURLsにオプションのフォーマット接尾辞を追加
現在、私たちの応答は、ある戻りフォーマットにハードバインドされていません.この利点を利用して、API側にフォーマットの接尾辞を追加することができます.フォーマット接尾辞を使用すると、指定したフォーマットを明確に指すようにURLsをカスタマイズできます.これは、APIがこのようなフォーマットhttp://example.com/api/items/4/.jsonのようないくつかのURLsを処理できることを意味します.
まず、次のようにformatキーワードパラメータを追加する必要があります.

def snippet_list(request, format=None):

さらに、

def snippet_detail(request, pk, format=None):

それからurls.pyファイルに対して、少し変更します.既存のURLsに加えて、format_suffix_patterns:

from django.conf.urls import url
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views

urlpatterns = [
    url(r'^snippets/$', views.snippet_list),
    url(r'^snippets/(?P[0-9]+)$', views.snippet_detail),
]

urlpatterns = format_suffix_patterns(urlpatterns)

フォーマットにサポートされているurlスタイル(patterns)を1つずつ追加する必要はありません.これは、特定のフォーマットを迅速にサポートするための簡潔な方法です.
効果はどうですか?
次に、チュートリアル1(tutorial part 1)の操作と同様に、コマンドラインからAPIをテストできます.私たちはいくつかの無効な要求に対して、良い処理を提供しましたが、まだあまり変わっていません.
私たちはすべてのsnippetのリストを取得することができます.前と同じです.

http http://127.0.0.1:8000/snippets/

HTTP/1.1 200 OK
...
[
  {
    "id": 1,
    "title": "",
    "code": "foo = \"bar\"
",
    "linenos": false,
    "language": "python",
    "style": "friendly"
  },
  {
    "id": 2,
    "title": "",
    "code": "print \"hello, world\"
",
    "linenos": false,
    "language": "python",
    "style": "friendly"
  }
]

また、HttpのAcceptヘッダ(header):

http http://127.0.0.1:8000/snippets/ Accept:application/json  #    JSON
http http://127.0.0.1:8000/snippets/ Accept:text/html         #    HTML

またはフォーマット接尾辞(format suffix):

http http://127.0.0.1:8000/snippets.json  # JSON   
http http://127.0.0.1:8000/snippets.api   #     API   

同様に、httpのContent-Typeヘッダ(header):

# POST       
http --form POST http://127.0.0.1:8000/snippets/ code="print 123"

{
  "id": 3,
  "title": "",
  "code": "print 123",
  "linenos": false,
  "language": "python",
  "style": "friendly"
}

# POST    JSON
http --json POST http://127.0.0.1:8000/snippets/ code="print 456"

{
    "id": 4,
    "title": "",
    "code": "print 456",
    "linenos": false,
    "language": "python",
    "style": "friendly"
}

ブラウザを使用してhttp://127.0.0.1:8000/snippets/ああ、APIをお願いします.
ビジュアル化
APIが応答フォーマットを選択するのは、クライアントによって開始された要求に基づいているため、ブラウザからの要求を受信すると、デフォルトではHTML形式でデータが記述される.これにより、APIは、Webブラウズ(web-browsable)のHTML表現を返すことができる.
Webブラウズ(web-browsable)を持つAPIは、APIの開発や使用に非常に役立ち、非常に便利になります.これにより、使用障壁が大幅に低減され、他の開発者が、より容易に閲覧し、使用できるようになります.
詳細については、ビジュアル化APIの特性とカスタマイズ方法については、トピック:ビジュアル化API(browsable api)を参照してください.
次は何をしますか.
チュートリアル第3部(tutorial part 3)では、クラスベースのビューを使用し始め、汎用ビュー(generic views)が大量のコードを節約する方法を見てみましょう.
もしあなたがこの翻訳がとても役に立つと思ったら、小額で私を賛助してもいいです.あなたの承認は、私の原動力です.