RESTful API 設計指南

阿新 • • 發佈：2020-08-03

網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮（手機、平板、桌面電腦、其他專用裝置......）。

因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致API構架的流行，甚至出現"API First"的設計思想。RESTful API是目前比較成熟的一套網際網路應用程式的API設計理論。我以前寫過一篇《理解RESTful架構》，探討如何理解這個概念。

今天，我將介紹RESTful API的設計細節，探討如何設計一套合理、好用的API。我的主要參考了兩篇文章（1，2）。

一、協議

API與使用者的通訊協議，總是使用HTTPs協議。

二、域名

應該儘量將API部署在專用域名之下。


https://api.example.com

如果確定API很簡單，不會有進一步擴充套件，可以考慮放在主域名下。


https://example.org/api/

三、版本（Versioning）

應該將API的版本號放入URL。


https://api.example.com/v1/

另一種做法是，將版本號放在HTTP頭資訊中，但不如放入URL方便和直觀。Github採用這種做法。

四、路徑（Endpoint）

路徑又稱"終點"（endpoint），表示API的具體網址。

在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與資料庫的表格名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用複數。

舉例來說，有一個API提供動物園（zoo）的資訊，還包括各種動物和僱員的資訊，則它的路徑應該設計成下面這樣。

https://api.example.com/v1/zoos

https://api.example.com/v1/animals

https://api.example.com/v1/employees

五、HTTP動詞

對於資源的具體操作型別，由HTTP動詞表示。

常用的HTTP動詞有下面五個（括號裡是對應的SQL命令）。

GET（SELECT）：從伺服器取出資源（一項或多項）。

POST（CREATE）：在伺服器新建一個資源。

PUT（UPDATE）：在伺服器更新資源（客戶端提供改變後的完整資源）。

PATCH（UPDATE）：在伺服器更新資源（客戶端提供改變的屬性）。

DELETE（DELETE）：從伺服器刪除資源。

還有兩個不常用的HTTP動詞。

HEAD：獲取資源的元資料。

OPTIONS：獲取資訊，關於資源的哪些屬性是客戶端可以改變的。

下面是一些例子。

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：刪除某個指定動物園的指定動物

六、過濾資訊（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 的含義是相同的。

七、狀態碼（Status Codes）

伺服器向用戶返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的HTTP動詞）。

200 OK - [GET]：伺服器成功返回使用者請求的資料，該操作是冪等的（Idempotent）。

201 CREATED - [POST/PUT/PATCH]：使用者新建或修改資料成功。

202 Accepted - [*]：表示一個請求已經進入後臺排隊（非同步任務）

204 NO CONTENT - [DELETE]：使用者刪除資料成功。

400 INVALID REQUEST - [POST/PUT/PATCH]：使用者發出的請求有錯誤，伺服器沒有進行新建或修改資料的操作，該操作是冪等的。

401 Unauthorized - [*]：表示使用者沒有許可權（令牌、使用者名稱、密碼錯誤）。

403 Forbidden - [*] 表示使用者得到授權（與401錯誤相對），但是訪問是被禁止的。

404 NOT FOUND - [*]：使用者發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是冪等的。

406 Not Acceptable - [GET]：使用者請求的格式不可得（比如使用者請求JSON格式，但是隻有XML格式）。

410 Gone -[GET]：使用者請求的資源被永久刪除，且不會再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個物件時，發生一個驗證錯誤。

500 INTERNAL SERVER ERROR - [*]：伺服器發生錯誤，使用者將無法判斷髮出的請求是否成功。

狀態碼的完全列表參見這裡。

八、錯誤處理（Error handling）

如果狀態碼是4xx，就應該向使用者返回出錯資訊。一般來說，返回的資訊中將error作為鍵名，出錯資訊作為鍵值即可。


{
    error: "Invalid API key"
}

九、返回結果

針對不同操作，伺服器向用戶返回的結果應該符合以下規範。

GET /collection：返回資源物件的列表（陣列）

GET /collection/resource：返回單個資源物件

POST /collection：返回新生成的資源物件

PUT /collection/resource：返回完整的資源物件

PATCH /collection/resource：返回完整的資源物件

DELETE /collection/resource：返回一個空文件

十、Hypermedia API

RESTful API最好做到Hypermedia，即返回結果中提供連結，連向其他API方法，使得使用者不查文件，也知道下一步應該做什麼。

比如，當用戶向api.example.com的根目錄發出請求，會得到這樣一個文件。


{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面程式碼表示，文件中有一個link屬性，使用者讀取這個屬性就知道下一步該呼叫什麼API了。rel表示這個API與當前網址的關係（collection關係，並給出該collection的網址），href表示API的路徑，title表示API的標題，type表示返回型別。

Hypermedia API的設計被稱為HATEOAS。Github的API就是這種設計，訪問api.github.com會得到一個所有可用API的網址列表。


{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

從上面可以看到，如果想獲取當前使用者的資訊，應該去訪問api.github.com/user，然後就得到了下面結果。


{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

上面程式碼表示，伺服器給出了提示資訊，以及文件的網址。

十一、其他

（1）API的身份認證應該使用OAuth 2.0框架。

（2）伺服器返回的資料格式，應該儘量使用JSON，避免使用XML。

RESTful是目前最流行的 API 設計規範，用於 Web 資料介面的設計。

它的大原則容易把握，但是細節不容易做對。本文總結 RESTful 的設計細節，介紹如何設計出易於理解和使用的 API。

一、URL 設計

1.1 動詞 + 賓語

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

動詞通常就是五種 HTTP 方法，對應 CRUD 操作。

GET：讀取（Read）

POST：新建（Create）

PUT：更新（Update）

PATCH：更新（Update），通常是部分更新

DELETE：刪除（Delete）

根據 HTTP 規範，動詞一律大寫。

1.2 動詞的覆蓋

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

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


POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

上面程式碼中，X-HTTP-Method-Override指定本次請求的方法是PUT，而不是POST。

1.3 賓語必須是名詞

賓語就是 API 的 URL，是 HTTP 動詞作用的物件。它應該是名詞，不能是動詞。比如，/articles這個 URL 就是正確的，而下面的 URL 不是名詞，所以都是錯誤的。

/getAllCars

/createNewCar

/deleteAllRedCars

1.4 複數 URL

既然 URL 是名詞，那麼應該使用複數，還是單數？

這沒有統一的規定，但是常見的操作是讀取一個集合，比如GET /articles（讀取所有文章），這裡明顯應該是複數。

為了統一起見，建議都使用複數 URL，比如GET /articles/2要好於GET /article/2。

1.5 避免多級 URL

常見的情況是，資源需要多級分類，因此很容易寫出多級的 URL，比如獲取某個作者的某一類文章。


GET /authors/12/categories/2

這種 URL 不利於擴充套件，語義也不明確，往往要想一會，才能明白含義。

更好的做法是，除了第一級，其他級別都用查詢字串表達。


GET /authors/12?categories=2

下面是另一個例子，查詢已釋出的文章。你可能會設計成下面的 URL。


GET /articles/published

查詢字串的寫法明顯更好。


GET /articles?published=true

二、狀態碼

2.1 狀態碼必須精確

客戶端的每一次請求，伺服器都必須給出迴應。迴應包括 HTTP 狀態碼和資料兩部分。

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

1xx：相關資訊

2xx：操作成功

3xx：重定向

4xx：客戶端錯誤

5xx：伺服器錯誤

這五大類總共包含100多種狀態碼，覆蓋了絕大部分可能遇到的情況。每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需檢視狀態碼，就可以判斷出發生了什麼情況，所以伺服器應該返回儘可能精確的狀態碼。

API 不需要1xx狀態碼，下面介紹其他四類狀態碼的精確含義。

2.2 2xx 狀態碼

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

GET: 200 OK

POST: 201 Created

PUT: 200 OK

PATCH: 200 OK

DELETE: 204 No Content

上面程式碼中，POST返回201狀態碼，表示生成了新的資源；DELETE返回204狀態碼，表示資源已經不存在。

此外，202 Accepted狀態碼錶示伺服器已經收到請求，但還未進行處理，會在未來再處理，通常用於非同步操作。下面是一個例子。


HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

2.3 3xx 狀態碼

API 用不到301狀態碼（永久重定向）和302狀態碼（暫時重定向，307也是這個含義），因為它們可以由應用級別返回，瀏覽器會直接跳轉，API 級別可以不考慮這兩種情況。

API 用到的3xx狀態碼，主要是303 See Other，表示參考另一個 URL。它與302和307的含義一樣，也是"暫時重定向"，區別在於302和307用於GET請求，而303用於POST、PUT和DELETE請求。收到303以後，瀏覽器不會自動跳轉，而會讓使用者自己決定下一步怎麼辦。下面是一個例子。


HTTP/1.1 303 See Other
Location: /api/orders/12345

2.4 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.5 5xx 狀態碼

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

500 Internal Server Error：客戶端請求有效，伺服器處理時發生了意外。

503 Service Unavailable：伺服器無法處理請求，一般用於網站維護狀態。

三、伺服器迴應

3.1 不要返回純本文

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

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


GET /orders/2 HTTP/1.1 
Accept: application/json

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

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


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

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

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

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


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

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

3.3 提供連結

API 的使用者未必知道，URL 是怎麼設計的。一個解決方法就是，在迴應中，給出相關連結，便於下一步操作。這樣的話，使用者只要記住一個 URL，就可以發現其他的 URL。這種方法叫做 HATEOAS。

舉例來說，GitHub 的 API 都在api.github.com這個域名。訪問它，就可以得到其他 URL。


{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}

上面的迴應中，挑一個 URL 訪問，又可以得到別的 URL。對於使用者來說，不需要記住 URL 設計，只要從 api.github.com 一步步查詢就可以了。

HATEOAS 的格式沒有統一規定，上面例子中，GitHub 將它們與其他屬性放在一起。更好的做法應該是，將相關連結與其他屬性分開。


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

{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}

四、參考連結

RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca
API design, by MicroSoft Azure

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html