[譯] RESTful API 設計指南 - 最佳實踐

原文: RESTful API Designing Guidelines — The Best Practices

Facebook、Google、GitHub、Netflix 和其餘一些科技巨頭都爲開發人員和產品提供了經過 API 來使用它們的數據。

即便你不爲其餘開發者或產品提供 API，但經過精細設計的 API 對你的應用也是有益的。

關於 API 設計的最佳實踐爭論了很長時間，並無一個官方的定義。

API 是開發人員與數據進行交互的接口。一個精心設計的 API 應該是易於使用的。

術語

下面列出來的是與 REST API 相關的重要術語。

• 資源（Resource） 實體對象或由一些相關聯數據及可對其操縱的方法組成的事物。例如：動物、學校和員工都是資源。增刪改查是對這些資源執行操做的方法
• 集合（Collections）一組資源，例如 companies 是 company 的集合
• URL用來定位資源和執行操做的路徑

API 終端（endpoint）

咱們經過公司員工的例子來理解。

/getAllEmployees 是一個 API 來獲取員工列表。圍繞着公司的其餘一些 API 以下：

• /addNewEmployee
• /updateEmployee
• /deleteEmployee
• /deleteAllEmployees
• /promoteEmployee
• /promoteAllEmployees

諸如此類不一樣操做的 API endpoint 會不少不少。你們會注意到每一個 API endpoint 都包含了動做（action）的描述，當 API 增長時 API endpoint 將會變得越來難以維護。

錯在哪裏？

URL 應該只包含資源（名詞），而不該該有動做（action）或動詞。API /addNewEmployee 包含動做 addNew 和資源名 Employee。

正確的方式是什麼？

/companies 是一個不包含動做的好例子。但問題是「咱們怎麼告訴服務器該對companies資源執行增刪改查？」

這就是 HTTP 方法（GET、POST、PUT、DELETE）派上用場的時候了。

資源名應該始終使用複數形式，若是想查看一個實例，能夠經過在 URL 中傳遞一個 ID。

• GET 方法 /companies：獲取全部公司列表
• GET 方法 /companies/34：獲取 ID 爲 34 的公司詳細信息
• DELETE 方法 /companies/34：刪除 ID 爲 34 的公司

其餘例子，若是一個資源（resources）在另外一個資源（resource）下，例如：一個公司的員工。

• GET /companies/3/employees/45 ID 爲 3 的公司裏 ID 爲 45 的員工信息
• DELETE /companies/3/employees/45 刪除 ID 爲 3 的公司裏 ID 爲 45 的員工
• POST /companies 建立新的公司，並返回新建立的公司詳細信息

如今的 API 是否是更清晰一致呢？

結論

路徑中的資源以複數形式存在，並經過 HTTP 方法對資源進行操做。

HTTP 方法

HTTP 定義了一些方法來指示對資源的操做。

1. GET 獲取資源數據，並不帶有反作用。例如：/companies/3/employees 返回 ID 爲 3 的公司裏全部的員工列表。
2. POST 請求服務器在數據庫中建立資源。例如：/companies/3/employees 給 ID 爲 3 的公司建立新的員工。POST 是非冪等的。
3. PUT 請求服務更新資源或建立一個不存在的資源。例如：/companies/3/employees/john 更新或建立 ID 爲 3 的公司下 employees 集合裏的 john。PUT 是冪等的。
4. DELETE 請求從數據庫中刪除某個資源。例如： /companies/3/employees/john/ 從 ID 爲 3 的公司 employees 集合裏的 john。

HTTP 響應狀態碼

當客戶端經過 API 請求服務器時，不論成功與否都應該知道反饋結果。

HTTP 狀態碼是幾組在不一樣情況下給出說明的標準化代碼，服務器應該返回正確的狀態碼。

2xx（成功）

表示服務器已經接收併成功處理了請求。

• 200 OK — 表示 GET、PUT 或 POST 成功
• 201 Created — 當有新的資源被建立時應該返回該狀態碼。例如：經過 POST 建立新資源，要返回 201
• 204 No Content — 表示請求已被成功處理但沒有返回任何內容。例如：DELETE /companies/43/employees/2 刪除 ID 爲 2 的員工，刪除成功後咱們不須要返回任何數據。若是出現錯誤，如 employee 2 在數據庫裏不存在，返回碼就不該該是 2xx Success，而是 4xx Client Error

3xxx（重定向）

• 304 Not Modified — 表示數據已被緩存。

4xx（客戶端錯誤）

這些狀態代碼表示客戶端發送了錯誤的請求。

• 400 Bad Request — 表示請求不能被處理，由於服務器不理解客戶端發起的請求。
• 401 Unauthorized — 不容許客戶端訪問的資源，須要使用憑證（credentials）請求
• 403 Forbidden — 表示請求有效並通了過身份認證，但出於某個緣由不容許訪問
• 404 Not Found — 表示資源不可用或找不到
• 410 Gone — 表示資源已被永久刪除，注意與 404 區別，資源之前存在但如今不存在會用 410 替代 404

5xx（服務器錯誤）

• 500 Internal Server Error — 表示請求有效，可是服務器端出現問題•503 Service Unavailable — 表示服務器宕機不能接收和處理請求。通常用在服務器維護期間

搜索、過濾、排序和分頁

這些操做只是對數據集的查詢。我麼須要在 GET API 中附加查詢參數。

• 排序 — 若是想獲取有序的公司列表。GET /companies 應該接受多個排序查詢參數。例如：GET /companies?sort=rank_asc 按公司升序排名排序
• 過濾 — 過濾數據集，經過傳不一樣的查詢參數。例如：GET /companies?category=banking&location=india 過濾出來在印度所屬銀行分類下的全部公司
• 搜索 — 例如：經過公司名搜索公司 GET /companies?search=Digital Mckinsey
• 分頁 — 當數據不少時，須要將數據進行拆分。例如：GET /companies?page=23

若是 GET 請求的參數過長，服務端可能會返回 414 URI Too long 狀態碼，這時咱們能夠經過 POST 方式並將參數放在請求體（body）裏。

版本控制

經過版本控制來升級你的 API，例子：http://api.yourservice.com/v1/companies/34/employees，若是有大版本升級，能夠命名新的 API 版本 v2 或 v1.x.x。

「極客閱讀 」匯聚了國內外最優質的技術博客、產品動態、公衆號文章。開發者能夠在極客閱讀一站式的閱讀到來自互聯網技術大咖的文章。

「極客閱讀 」官網：geeker-read.com