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 。
您需要安裝coreapi
python包以包含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