教程7：模式和客户端库

模式是一种机器可读文档，用于描述可用的API端点，其URLS以及它们支持的操作。

模式可以是自动生成文档的有用工具，也可用于驱动可与API进行交互的动态客户端库。

核心API

为了提供架构支持，REST框架使用。

Core API是用于描述API的文档规范。它用于提供可用端点的内部表示格式和API暴露的可能交互。它可以用于服务器端或客户端。

当使用服务器端时，Core API允许API支持各种模式或超媒体格式的渲染。

当客户端使用时，Core API允许动态驱动的客户端库可以与暴露支持的模式或超媒体格式的任何API进行交互。

添加模式

REST框架支持明确定义的模式视图或自动生成的模式。由于我们使用的是视图集和路由器，我们可以简单地使用自动模式生成。

您需要安装coreapipython包才能包含API模式。

$ pip install coreapi

现在我们可以通过在URL配置中包含一个自动生成的模式视图来为API添加模式。

from rest_framework.schemas import get_schema_view schema_view = get_schema_view(title='Pastebin API') urlpatterns = [ url(r'^schema/$', schema_view), ... ]

如果您在浏览器中访问API根端点，则现在应该可以看到corejson 表示形式可用作选项。

我们还可以通过在Accept标题中指定所需的内容类型从命令行请求模式。

$ http http://127.0.0.1:8000/schema/ Accept:application/coreapi+jsonHTTP/1.0 200 OK Allow: GET, HEAD, OPTIONS Content-Type: application/coreapi+json { "_meta": { "title": "Pastebin API" }, "_type": "document", ...

默认输出样式是使用编码。

还支持其他模式格式，例如（以前称为Swagger）。

使用命令行客户机

现在我们的API暴露了架构端点，我们可以使用动态客户端库来与API进行交互。为了演示这个，我们来使用Core API命令行客户端。

命令行客户端可用作coreapi-cli包：

$ pip install coreapi-cli

现在检查它在命令行上可用...

$ coreapiUsage: coreapi [OPTIONS] COMMAND [ARGS]... Command line client for interacting with CoreAPI services. Visit http://www.coreapi.org for more information. Options: --version Display the package version number. --help Show this message and exit. Commands: ...

首先，我们将使用命令行客户机加载API模式。

$ coreapi get http://127.0.0.1:8000/schema/ 
    
      snippets: { highlight(id) list() read(id) } users: { list() read(id) }
    

我们还没有认证，所以现在我们只能看到只读端点，这与我们如何设置API的权限一致。

我们尝试列出现有的片段，使用命令行客户端：

$ coreapi action snippets list[    {
       "url": "http://127.0.0.1:8000/snippets/1/", "id": 1, "highlight": "http://127.0.0.1:8000/snippets/1/highlight/", "owner": "lucy", "title": "Example", "code": "print('hello, world!')", "linenos": true, "language": "python", "style": "friendly" }, ...

一些API端点需要命名参数。例如，要获取特定代码段的高亮度HTML，我们需要提供一个id。

$ coreapi action snippets highlight --param id=1     ...

认证我们的客户

如果我们想要创建，编辑和删除片段，我们需要作为有效用户进行身份验证。在这种情况下，我们只需使用基本的auth。

确保更换<username>，并<password>与您的实际用户名和密码下面。

$ coreapi credentials add 127.0.0.1 
    
     :
     
       --auth basic Added credentials 127.0.0.1 "Basic <...>"
     
    

现在，如果我们再次获取架构，我们应该可以看到一整套可用的交互。

$ coreapi reloadPastebin API "http://127.0.0.1:8000/schema/"> snippets: { create(code, [title], [linenos], [language], [style]) delete(id) highlight(id) list() partial_update(id, [title], [code], [linenos], [language], [style]) read(id) update(id, code, [title], [linenos], [language], [style]) } users: { list() read(id) }

我们现在可以与这些端点进行交互。例如，要创建一个新的代码段：

$ coreapi action snippets create --param title="Example" --param code="print('hello, world')" { "url": "http://127.0.0.1:8000/snippets/7/", "id": 7, "highlight": "http://127.0.0.1:8000/snippets/7/highlight/", "owner": "lucy", "title": "Example", "code": "print('hello, world')", "linenos": false, "language": "python", "style": "friendly" }

并删除片段：

$ coreapi action snippets delete --param id=7

除了命令行客户端，开发人员还可以使用客户端库与您的API进行交互。Python客户端库是第一个可用的，并且计划即将发布一个Javascript客户端库。

有关定制模式生成和使用Core API客户端库的更多详细信息，您需要参考完整的文档。

回顾我们的工作

我们现在拥有一个非常少量的代码，它拥有完整的可以浏览网页的粘贴程式Web API，它包含一个模式驱动的客户端库，并具有身份验证，每个对象权限和多个渲染器格式。

我们已经走过了设计过程的每个步骤，并且了解了如果我们需要自定义任何我们可以逐渐工作的方式，以简单地使用常规的Django视图。

 

现在去构建真棒的东西