1. 程式人生 > >API(七)之Schemas & client libraries

API(七)之Schemas & client libraries

for span package rgs splay num hyper true dia

模式是一種機器可讀的文檔,用於描述可用的API端點,其URLS以及它們支持的操作。

模式可以是自動生成文檔的有用工具,也可以用於驅動可以與API進行交互的動態客戶端庫。

Core API

為了提供支持REST框架的schema而使用Core API。

Core API是用於描述API的文檔規範。它用於提供可用端點的內部表現格式以及API暴露的可能的交互。它可以用於服務器端或客戶端。

當使用服務器端時,Core API允許API支持各種模式或超媒體格式的渲染。

When used client-side, Core API allows for dynamically driven client libraries that can interact with any API that exposes a supported schema or hypermedia format.

Adding a schema

REST框架支持明確定義的 schema views 或自動生成的 schemas 。由於我們使用的是 viewsets and routers,我們可以只使用 the automatic schema generation 。

您需要安裝coreapipython包以包含API schema 。

pip install coreapi

現在我們可以通過在URL配置中包含一個自動生成的 schema view 來為API添加一個 schema 。

from rest_framework.schemas import get_schema_view

schema_view = get_schema_view(title=‘Pastebin API‘)

urlpatterns = [
    url(r‘^schema/$‘, schema_view),
    ...
]

如果您在瀏覽器中訪問API根端點,那麽您現在應該可以看到corejson 表現層變成了一個可用的選項。

技術分享

我們還可以通過在Accept header中指定所需的內容類型來從命令行請求 schema 。

$ 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編碼。

還支持其他架構格式,如Open API(以前稱為Swagger)。

Using a command line client

現在我們的API暴露了一個 schema endpoint,我們可以使用一個動態的客戶端庫來與API進行交互。為了演示這個,我們來使用Core API命令行客戶端。

命令行客戶端可用作coreapi-cli包:

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

我們還沒有認證,所以現在我們只能看到只讀端點,這與我們已經設置的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>
  ...

Authenticating our client

如果我們想要創建,編輯和刪除代碼片段,我們需要作為有效用戶進行身份驗證。在這種情況下,我們只需使用基本的auth。

確保用您的實際用戶名和密碼更換下面的<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客戶端庫是第一個可用的,並且計劃即將發布一個Javascript客戶端庫。

有關定制模式生成和使用Core API客戶端庫的更多詳細信息,您需要參考完整的文檔。

API(七)之Schemas & client libraries