模式是一个机器可读的文档,描述了可用的API端点,它们的URL以及它们支持的操作。
模式可以是自动生成文档的有用工具,也可以用于驱动可以与API交互的动态客户端库。
核心API
为了提供架构支持,REST框架使用了Core API。
核心API是用于描述API的文档规范。它用于提供可用端点的内部表示格式以及API公开的可能交互。它既可以用于服务器端,也可以用于客户端。
在服务器端使用时,Core API允许API支持呈现各种模式或超媒体格式。
在客户端使用时,Core API允许动态驱动的客户端库可以与任何公开支持的模式或超媒体格式的API进行交互。
添加架构
REST框架支持显式定义的模式视图或自动生成的模式。由于我们使用的是视图集和路由器,因此我们可以简单地使用自动模式生成。
您需要安装coreapi
python包以包含API模式,并将pyyaml
模式呈现为常用的基于YAML的OpenAPI格式。
$ pip install coreapi pyyaml
我们现在可以通过在URL配置中包含自动生成的模式视图来为我们的API包含模式。
from rest_framework.schemas import get_schema_view
schema_view = get_schema_view(title='Pastebin API')
urlpatterns = [
url('', include(router.urls)),
url(r'^schema/$', schema_view),
]
# urlpatterns = format_suffix_patterns(urlpatterns)
# 这里我注销了,不然会报错,原因还暂未知
# django.core.exceptions.ImproperlyConfigured: "^snippets\.(?P<format>[a-z0-9]+)/?\.(?P<format>[a-z0-9]+)/?$" is not a valid regular expression: redefinition of group name 'format' as group 2; was group 1 at position 40
API测试
测试结果输出为core json 格式
使用命令行客户端
现在我们的API公开了一个模式端点,我们可以使用动态客户端库与API进行交互。为了演示这一点,让我们使用Core API命令行客户端。
命令行客户端作为coreapi-cli
包提供:
$ pip install coreapi-cli
现在检查它是否在命令行上可用
# windows 同linux
$ coreapi get http://127.0.0.1:8000/schema/
<Pastebin API "http://127.0.0.1:8000/schema/">
snippets: {
highlight(id)
list()
read(id)
}
users: {
list()
read(id)
}
首先,我们将使用命令行客户端加载API模式。
$ coreapi get http://127.0.0.1:8000/schema/
<Pastebin API "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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Example</title>
...
验证我们的客户
如果我们希望能够创建,编辑和删除代码段,我们需要作为有效用户进行身份验证。在这种情况下,我们将只使用基本身份验证。
确保更换<username>
,并<password>
与您的实际用户名和密码下面。
$ coreapi credentials add 127.0.0.1 <username>:<password> --auth basic
Added credentials
127.0.0.1 "Basic <...>"
现在,如果我们再次获取模式,我们应该能够看到完整的可用交互集。
$ coreapi reload
Pastebin 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客户端库。
总结:
模式是对网站接口的规范文档化
客户端库:,个人感觉作用类试于API测试管理工具,例如:postman,Swagger等