RESTful API 最佳實踐

阿新 • • 發佈：2019-12-31

RESTful API 最佳實踐

RESTful 是目前最流行的 API 規範，適用於 Web 介面規範的設計。讓介面易讀，且含義清晰。本文將介紹如何設計易於理解和使用的 API，並且藉助 Docker api 的實踐說明。

URL 設計

1.1 動詞 + 賓語

它的核心思想就是客戶端發出的資料操作指令都是「動詞 + 賓語」的結構，比如 GET /articles這個命令，GET是動詞，/articles是賓語。

動詞通常來說就是五種 HTTP 方法，對應我們業務介面的 CRUD 操作。而賓語就是我們要操作的資源，可以理解成面向資源設計。我們所關注的資料就是資源。

GET: 讀取資源
POST：新建資源

PUT：更新資源
PATCH：資源部分資料更新
DELETE：刪除資源

正確的例子

GET /zoos：列出所有動物園
POST /zoos：新建一個動物園
GET /zoos/ID：獲取某個指定動物園的資訊
PUT /zoos/ID：更新某個指定動物園的資訊（提供該動物園的全部資訊）
PATCH /zoos/ID：更新某個指定動物園的資訊（提供該動物園的部分資訊）
DELETE /zoos/ID：刪除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

1.2 動詞的覆蓋

有些客戶端只能使用GET和POST這兩種方法。伺服器必須接受 POST 模擬其他三個方法（PUT、PATCH、DELETE）。

這時，客戶端發出的 HTTP 請求，要加上 X-HTTP-Method-Override 屬性，告訴伺服器應該使用哪一個動詞，覆蓋 POST 方法。

1.3 賓語必須是名詞

就是 API 的url ，是 HTTP 動詞作用的物件，所以應該是名詞。例如 /books 這個 URL 就是正確的，而下面的 URL 不是名詞，都是錯誤的寫法。

錯誤示範：

GET /getAllUsers?name=jl
POST /createUser
POST /deleteUSer
複製程式碼

1.4 複數名詞

URL 是名詞，那麼是使用複數還是單數？

沒有統一的規定，但是我們通常操作的資料多數是一個集合，比如 GET /books

,所以我們就使用複數。

統一規範，建議都使用複數 URL，比如獲取 id = 2 的書 GET /books/2 要好於 GET /book/2。

1.5 避免出現多級 URL

有時候我們要操作的資源可能是有多個層級，因此很容易寫多級 URL，比如獲取某個作者某種分類的文章。

GET /authors/2/categories/2 獲取作者ID = 2 分類 = 2 的文章

這種 URL 不利於拓展，語義也不清晰。

更好的方式就是除了第一級，其他級別都是通過查詢字串表達。

正確方式： GET /authors/12?categories=2

查詢已釋出的文章

錯誤寫法： GET /artichels/published

正確寫法： GET /artichels?published=true

過濾資訊（Filtering）

狀態碼如果記錄數量很多，伺服器不可能都將它們返回給使用者。API應該提供引數，過濾返回結果。

下面是一些常見的引數。

?limit=10：指定返回記錄的數量

?offset=10：指定返回記錄的開始位置。

?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。

?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。

?animal_type_id=1：指定篩選條件

引數的設計允許存在冗餘，即允許API路徑和URL引數偶爾有重複。比如，GET /zoo/ID/animals 與 GET /animals?zoo-id=ID 的含義是相同的。推薦後者，避免出現多級URL。

2.1 狀態碼必須精確

客戶端的請求，服務求都必須響應，包含 HTTP 狀態碼和資料。

HTTP 狀態碼就是一個三位數，分成五個類別。

1xx：相關資訊
2xx：操作成功
3xx：重定向
4xx：客戶端錯誤
5xx：伺服器錯誤

2.2 2xx 狀態碼

200狀態碼錶示操作成功，但是不同的方法可以返回更精確的狀態碼。

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

2.3 4xx 狀態碼

4xx狀態碼錶示客戶端錯誤，主要有下面幾種。

400 Bad Request：伺服器不理解客戶端的請求，未做任何處理。
401 Unauthorized：使用者未提供身份驗證憑據，或者沒有通過身份驗證。
403 Forbidden：使用者通過了身份驗證，但是不具有訪問資源所需的許可權。
404 Not Found：所請求的資源不存在，或不可用。
405 Method Not Allowed：使用者已經通過身份驗證，但是所用的 HTTP 方法不在他的許可權之內。
410 Gone：所請求的資源已從這個地址轉移，不再可用。
415 Unsupported Media Type：客戶端要求的返回格式不支援。比如，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式。
422 Unprocessable Entity ：客戶端上傳的附件無法處理，導致請求失敗。
429 Too Many Requests：客戶端的請求次數超過限額。

2.4 5xx 狀態碼

5xx狀態碼錶示服務端錯誤。一般來說，API 不會向用戶透露伺服器的詳細資訊，所以只要兩個狀態碼就夠了。

500 Internal Server Error：客戶端請求有效，伺服器處理時發生了意外。
503 Service Unavailable：伺服器無法處理請求，一般用於網站維護狀態。

伺服器響應

3.1 不要返回純文字

API 返回的資料格式，不應該是純文字，而應該是一個 JSON 物件，因為這樣才能返回標準的結構化資料。所以，伺服器迴應的 HTTP 頭的 Content-Type 屬性要設為 application/json 。

客戶端請求時，也要明確告訴伺服器，可以接受 JSON 格式，即請求的 HTTP 頭的ACCEPT 屬性也要設成 application/json。下面是一個例子。

3.2 發生錯誤的時候，不要返回 200 狀態碼

有一種不恰當的做法是，即使發生錯誤，也返回200狀態碼，把錯誤資訊放在資料體裡面，就像下面這樣。

錯誤例子：

HTTP/1.1 200 OK
ConteNTP-Type: application/json

{
	"status": "fail","msg": "錯誤"
}
複製程式碼

上面程式碼中，解析資料體以後，才能得知操作失敗。

這張做法實際上取消了狀態碼，這是完全不可取的。正確的做法是，狀態碼反映發生的錯誤，具體的錯誤資訊放在資料體裡面返回。下面是一個例子。

正確方式：

HTTP/1.1 400 Bad Request
ConteNTP-Type: application/json

{
	"status": "fail","msg": "錯誤"
}
複製程式碼

docker RESTful 規範解析

接下來我們分析 docker api 對於 restful 的使用，助於我們在實際工作中合理設計。

docker 檔案 url ：docs.docker.com/engine/api/…

4.1 GET 獲取容器列表

GET /v1.19/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1

通過 all=1&before=8dfafdbc3a40&size=1 過濾容器資料

4.2 GET 獲取指定ID或者名字容器

GET /containers/(id or name)/json

GET /v1.19/containers/4fa6e0f0c678/json HTTP/1.1

4.3 GET 獲取某個容器的程式

GET /v1.19/containers/4fa6e0f0c678/top HTTP/1.1

假如想過濾程式等可以通過查詢字串實現

GET /v1.19/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1

返回的資料

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Titles" : [
    "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
  ]
  "Processes" : [
    [
      "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
    ],[
      "root","13895","4348","692","S+","17:15","sleep 10"
    ]
  ],}
複製程式碼

4.4 POST 建立容器

POST /containers/create

POST /v1.19/containers/create HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
       "Hostname": "","Domainname": "","User": "","AttachStdin": false,"AttachStdout": true,"AttachStderr": true,"Tty": false,"OpenStdin": false,"StdinOnce": false,"Env": [
               "FOO=bar","BAZ=quux"
       ],"Cmd": [
               "date"
       ],"Entrypoint": null,"Image": "ubuntu","Labels": {
               "com.example.vendor": "Acme","com.example.license": "GPL","com.example.version": "1.0"
       },"Volumes": {
         "/volumes/data": {}
       }
   
  }
複製程式碼

4.5 DELETE 刪除容器

根據容器 id 刪除一個容器，v是請求是否刪除容器 volumes

DELETE /v1.19/containers/16253994b7c4?v=1 HTTP/1.1

Query parameters:

v – 1/True/true or 0/False/false,Remove the volumes associated to the container. Default false.
force - 1/True/true or 0/False/false,Kill then remove the container. Default false.
link - 1/True/true or 0/False/false,Remove the specified link associated to the container. Default false.