教程 2：请求和响应

从现在开始，我们将真正开始接触 REST framework 的核心。 我们来介绍几个基本的构建模块。

请求对象 (request objects)

REST framework 引入了一个扩展了常规 HttpRequest 的 Request 对象，并提供了更灵活的请求解析。Request 对象的核心功能是 request.data 属性，它与 request.POST 类似，但对于使用 Web API 更加有用。

  1. request.POST # 只处理表单数据。 只适用于 'POST' 方法。
  2. request.data # 处理任意数据。 适用于 'POST'，'PUT' 和 'PATCH' 方法。

响应对象 (Response objects)

REST framework 还引入了一个 Response 对象，该对象是一种获取未渲染内容的 TemplateResponse 类型，并使用内容协商来确定正确内容类型返回给客户端。

  1. return Response(data) # 渲染成客户端请求的内容类型。

状态码 (Status codes)

在您的视图中使用数字 HTTP 状态码并不总是利于代码的阅读，如果写错代码，很容易被忽略。REST framework 为每个状态码提供更明确的标识符，譬如 status 模块中的 HTTP_400_BAD_REQUEST。使用它们是一个好主意，而不是使用数字标识符。

包装 API 视图 (Wrapping API views)

REST framework 提供了两种编写 API 视图的封装。

  1. 用于基于函数视图的 @api_view 装饰器。
  2. 用于基于类视图的 APIView 类。

这些视图封装提供了一些功能，例如确保你的视图能够接收 Request 实例，并将上下文添加到 Response 对象，使得内容协商可以正常的运作。

视图封装还内置了一些行为，例如在适当的时候返回 405 Method Not Allowed 响应，并处理访问错误的输入 request.data 时触发的任何 ParseError 异常。

组合在一起

好的，让我们开始使用这些新的组件来写几个视图。

我们不再需要 views.py 中 JSONResponse 类，所以把它删除掉。然后，我们可以重构我们的视图。

  1. @api_view(['GET', 'POST'])
  2. def snippet_list(request):
  3.     """
  4.     列出所有的代码 snippet，或创建一个新的 snippet。
  5.     """
  6.     if request.method == 'GET':
  7.         snippets = Snippet.objects.all()
  8.         serializer = SnippetSerializer(snippets, many=True)
  9.         return Response(serializer.data)
  11.     elif request.method == 'POST':
  12.         serializer = SnippetSerializer(data=request.data)
  13.         if serializer.is_valid():
  14.             serializer.save()
  15.             return Response(serializer.data, status=status.HTTP_201_CREATED)
  16.     return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

我们的实例视图比前面的示例有所改进。它稍微简洁一点，现在的代码与我们使用 Forms API 时非常相似。我们还使用了指定的状态码，这使得响应更加明显。

以下是 views.py 模块中单个 snippet 的视图。

  1. @api_view(['GET', 'PUT', 'DELETE'])
  2. def snippet_detail(request, pk):
  3.     """
  4.     获取，更新或删除一个代码 snippet
  5.     """
  6.     try:
  7.         snippet = Snippet.objects.get(pk=pk)
  8.     except Snippet.DoesNotExist:
  9.         return Response(status=status.HTTP_404_NOT_FOUND)
  11.     if request.method == 'GET':
  12.         serializer = SnippetSerializer(snippet)
  13.         return Response(serializer.data)
  15.     elif request.method == 'PUT':
  16.         serializer = SnippetSerializer(snippet, data=request.data)
  17.         if serializer.is_valid():
  18.             serializer.save()
  19.             return Response(serializer.data)
  20.         return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
  22.     elif request.method == 'DELETE':
  23.         snippet.delete()
  24.         return Response(status=status.HTTP_204_NO_CONTENT)

这对我们来说应该都是非常熟悉的 - 它和正常 Django 视图并没有什么不同。

注意，我们不再显式地将请求或响应绑定到给定的内容类型。request.data 可以处理传入的 json 请求，但它也可以处理其他格式。同样，我们返回带有数据的响应对象，但允许 REST framework 将响应渲染成正确的内容类型。

为我们的网址添加可选的格式后缀

为了利用我们的响应不再被硬连接到单个内容类型的事实，让我们将格式后缀的支持添加到我们的API端点。使用格式后缀，为我们提供了明确指向给定格式的 URL，这意味着我们的 API 可以处理一些 URLs，类似这样的格式 http://example.com/api/items/4.json。

像下面这样在这两个视图中添加一个 format 关键字参数。

  1. def snippet_list(request, format=None):

和

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

现在更新 snippet/urls.py 文件，在现有的 urls 基础上追加一组 format_suffix_patterns 。

  1. from django.conf.urls import url
  2. from rest_framework.urlpatterns import format_suffix_patterns
  3. from snippets import views
  5. urlpatterns = [
  6.     url(r'^snippets/$', views.snippet_list),
  7.     url(r'^snippets/(?P<pk>[0-9]+)$', views.snippet_detail),
  8. ]
  10. urlpatterns = format_suffix_patterns(urlpatterns)

我们不一定需要添加这些额外的 url 模式，但它给了我们一个简单，清晰的方式来引用特定的格式。

它看起来如何？

继续从命令行测试 API，就像我们在教程第一部分所做的那样。一切都非常类似，尽管我们对一些无效的请求有更好的错误处理。

我们可以像以前一样获取所有 snippet 的列表。

  1. (env) fang@ubuntu:~/django_rest_framework/tutorial$ http http://127.0.0.1:8000/snippets/
  2. HTTP/1.1 200 OK
  3. Allow: POST, OPTIONS, GET
  4. Content-Length: 317
  5. Content-Type: application/json
  6. Date: Thu, 14 Jun 2018 15:49:40 GMT
  7. Server: WSGIServer/0.2 CPython/3.5.2
  8. Vary: Accept, Cookie
  9. X-Frame-Options: SAMEORIGIN
  11. [
  12.     {
  13.         "code": "foo = \"bar\"\n",
  14.         "id": 1,
  15.         "language": "python",
  16.         "linenos": false,
  17.         "style": "friendly",
  18.         "title": ""
  19.     },
  20.     {
  21.         "code": "print \"hello, world\"\n",
  22.         "id": 2,
  23.         "language": "python",
  24.         "linenos": false,
  25.         "style": "friendly",
  26.         "title": ""
  27.     },
  28.     {
  29.         "code": "print \"hello, world\"",
  30.         "id": 3,
  31.         "language": "python",
  32.         "linenos": false,
  33.         "style": "friendly",
  34.         "title": ""
  35.     }
  36. ]

我们可以通过使用 Accept 请求头，来控制我们返回的响应的格式。

  1. http http://127.0.0.1:8000/snippets/ Accept:application/json  # 请求 JSON
  2. http http://127.0.0.1:8000/snippets/ Accept:text/html         # 请求 HTML

或者通过追加格式后缀：

  1. http http://127.0.0.1:8000/snippets.json  # JSON 后缀
  2. http http://127.0.0.1:8000/snippets.api   # 可浏览 API 后缀

类似的，我们可以通过 Content-Type 请求头来控制我们发送请求的格式。

  1. # POST 表单数据
  2. (env) fang@ubuntu:~/django_rest_framework/tutorial$ http --form POST http://127.0.0.1:8000/snippets/ code="print 123"
  3. HTTP/1.1 201 Created
  4. Allow: POST, OPTIONS, GET
  5. Content-Length: 93
  6. Content-Type: application/json
  7. Date: Thu, 14 Jun 2018 16:00:37 GMT
  8. Server: WSGIServer/0.2 CPython/3.5.2
  9. Vary: Accept, Cookie
  10. X-Frame-Options: SAMEORIGIN
  12. {
  13.     "code": "print 123",
  14.     "id": 4,
  15.     "language": "python",
  16.     "linenos": false,
  17.     "style": "friendly",
  18.     "title": ""
  19. }
  21. # POST JSON 数据
  22. (env) fang@ubuntu:~/django_rest_framework/tutorial$ http --json POST http://127.0.0.1:8000/snippets/ code="print 456"
  23. HTTP/1.1 201 Created
  24. Allow: POST, OPTIONS, GET
  25. Content-Length: 93
  26. Content-Type: application/json
  27. Date: Thu, 14 Jun 2018 16:02:24 GMT
  28. Server: WSGIServer/0.2 CPython/3.5.2
  29. Vary: Accept, Cookie
  30. X-Frame-Options: SAMEORIGIN
  32. {
  33.     "code": "print 456",
  34.     "id": 5,
  35.     "language": "python",
  36.     "linenos": false,
  37.     "style": "friendly",
  38.     "title": ""
  39. }

如果你向上述 http 请求中添加 --debug ，则可以在请求头中查看请求类型。

现在可以在浏览器中访问 http://127.0.0.1:8000/snippets/ 查看 API 。

可视化

由于 API 是基于客户端发起的请求来选择响应内容的格式，因此，当接收到来自浏览器的请求时，会默认以 HTML 格式来描述数据。这允许 API 返回网页完全可浏览的 HTML。

拥有可浏览的网页 API 是一个巨大的胜利，并且使开发和使用 API 更加容易。它也大大降低了其他开发人员检查和使用 API 的门槛。

有关可浏览的 API 功能以及如何对其进行定制的更多信息，请参阅可浏览的 API主题。

下一步是什么？

在教程的第三部分，我们将开始使用基于类的视图，并查看通用视图如何减少我们需要编写的代码量。