Django REST framework 第七章 Schemas & client libraries

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

模式对于自动生成文档是一个很有用的工具，也可以用来动态调用可以于API交互的客户端库。

 

Core API

为了提供模式支持，REST framework 使用核心API。

核心API是描述API的规范文档，它被用来提供可用端点的内部表现方式和API公开的可能的交互。它既可以在服务器端，也可以在客户端。

当使用在服务器端，核心代码允许API来支持对各种模式或者超媒体格式的渲染。当使用在客户端，核心API允许动态驱动客户端库，可以跟公开支持的模式或者超媒体格式的任何API交互。

 

Adding a schema

REST framework 支持明确定义模式视图或者自动生成模式。由于使用了视图集（viewset）和路由（router），可以简化使用自动模式生成。

你可能需要安装 coreapi python包

pip3 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),
    ...
]

如果访问/visit/端点在浏览器上，你现在可以看到corejson变成一个可选选项。

我们也可以从命令行请求

默认的输出格式是使用Core Json编码的。其他模式格式，比如Open API也是支持的

 

Using a command line client

现在我们的API暴露了一个模式端点，我们可以使用一个动态的客户端库来与API交互。为了演示这一点，让我们使用核心API命令行客户端。

首先安装模块：

pip3 install coreapi-cli

用法：

现在使用命令行客户端加载API模式

还没有认证，所以现在我们只能看到只读的端点。

使用命令行客户端，列出存在的snippet

一些API端点需要带名称的参数，比如，回到之前高亮的HTML里面某一个特殊的snippet，需要提供一个id

 

Authenticating our client

如果想要创建，编辑，删除snippets，就需要验证是否为一个合法的用户。在这个事例里，我们只是使用了基础的验证。

shuais-MBP:~ dandyzhang$ coreapi credentials add 127.0.0.1 dandy:password.1 --auth basic
Added credentials
127.0.0.1 "Basic ZGFuZHk6cGFzc3dvcmQuMQ=="

现在再去访问之前的模式，就能够看到整个可以可用的交互了。

现在可以跟这些端点交互了。例如创建一个新的snippet

同样的，也可以进行删除

shuais-MBP:~ dandyzhang$ coreapi action app01 snippets delete --param id=1

和命令行客户端一样，开发者也可以使用客户端库来跟你的API交互。