API(七)之Schemas & client libraries
模式是一種機器可讀的文檔，用於描述可用的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