模式是一个机器可读文档,描述可用的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交互。