教程7--Schemas和客户端库

最新推荐文章于 2022-09-22 16:06:08 发布

大海梦想

最新推荐文章于 2022-09-22 16:06:08 发布

阅读量885

点赞数 1

分类专栏： python 瞎翻译文章标签： python django

瞎翻译同时被 2 个专栏收录

8 篇文章 0 订阅

订阅专栏

python

7 篇文章 0 订阅

订阅专栏

教程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_view

schema_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上查看完整代码，或者在沙盒中感受一下这个完整的示例。