教程7–Schemas和客户端库

schema是集中机器可读的文档，用以描述API，URLS以及他们支持的操作。
Schemas可用于自动生成文档，也可以用来驱动动态客户端库的使用。

Core API

为了能够提供schema支持，REST框架使用了Core API。
Core API是一种描述API的文档规范，它被用来提供一个API的可用端点和可能的交互内部表示格式。它可以使服务器端，也可以是客户端。
如果是服务器端，Core API允许一个API支持渲染成广泛的Schema或者超媒体格式。
如果是客户端，Core API允许动态驱动客户端库来与任何的API交互，通过被支持的schema或者超媒体类型。

添加一个schema

REST框架支持明确声明schema视图，或者自动生成schemas。如果我们使用viewsets和routers，那么我们就可以自动生成schema了。
你需要安装coreapi：

$ pip install coreapi

现在，我们可以通过在URL配置中包含一个schema view来引入schema。

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

如果你此时访问API root，你会发现一个corejson的选项。

我们也可以在在命令行访问schema，在Acceptheader中指定媒体类型即可。

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

默认的输出风格是使用了Core JSON编码。
其他的schema格式，例如OpenApi(Swagger)也是支持的。

使用命令行客户端

现在我们API已经暴露了schema，我们可以使用动态客户端库来与这些API进行交互。

pip install coreapi-cli

现在检查一下是否安装成功。

$ coreapi
Usage: 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 Schema。

$ 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)}

目前我们还没有登录，所以只能读不能写，让我们先来试试列出所有snippet：

$ 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需要提供参数，可以这样做：

$ 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 <...>"

现在，如果我们重新拉取schema，我们可以看到一份完整的可操作的交互列表。

$ 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客户端是您的第一选择，JS的客户端也计划很快推出。
关于自定义Schema生成和使用 Core API 客户端类库的更多细节，请参考官方文档。

总结

我们只用了少量的代码，就有了一个完整的Web API，这是完全基于WEB可浏览的，包括一个schema驱动的客户端类库，和权限认证，对象级权限，多格式渲染等。
我们已经一起走过了开发的每一个步骤，并知道了如何自定义Django视图。
你可以在GitHub上查看完整代码，或者在沙盒中感受一下这个完整的示例。

继续探索

到这里为止，我们的教程就全部结束了。如果你希望更多地参与到REST框架项目中来，有这样几种选择：

在Github上提交issues，或者pull requests。
加入REST framework discussion group，帮助我们一起建设社区。
在Twitter上关注作者

现在，去创造令人拍案叫绝的项目吧！