RESTful API 設計指南——最佳實踐

oschina發表於2017-03-03
RESTAPI

　　Facebook、谷歌、Github、Netflix 和幾個其他的科技巨頭已經允許開發者和其產品通過 API 呼叫他們的資料，併為他們提供平臺。即使你不是寫 API 的專業人士，擁有精美的 API 也對你的應用程式有好處。

　　關於設計 API 的最好方法，網路上有較長一段時間的爭論，但官方也沒有對此給出解釋。

　　API 是一個介面，通過它許多開發者可與資料互動。 設計優良的 API 使用起來很方便，並給開發者的工作帶來便利。 API 是開發者的 GUI，如果它設計不合理，開發者會將它替換。所以，開發者的經驗是衡量 API 質量的最重要的指標。

API就像一個在舞臺上表演的藝術家，其使用者就是其觀眾

　　1) 術語

　　以下是與 REST API 相關的重要術語：

  • 資源（Resource） 是一個物件或對某物的表示。它有一些相關聯的資料，並有一組方法進行操作。 例如：動物，學校和員工是資源。這些資源都有著刪除，新增，更新操作。

  • 集合（Collection）是一系列資源，例如：公司集合是很多公司的集合。

  • URL（統一資源定位符）是一種路徑，可以通過它定位資源並且也可以對它執行一些動作。

　　2) API 端點（路徑）

　　為了更好理解，我們給公司寫 API，這些公司都有一些員工。/getAllEmployees 是對員工列表進行回應的 API。公司其他 API 大致如下:

  • /addNewEmployee

  • /updateEmployee

  • /deleteEmployee

  • /deleteAllEmployees

  • /promoteEmployee

  • /promoteAllEmployees

　　並且將有大量的和這些操作不同的 API 端點，它們包含大量冗餘的行為。因此，當 API 數量增加時，這些 API 端點將很難維護。

　　哪裡不對？

　　每個 URL 代表一種資源（Resource），所以 URL 中只能有名詞，不能有動詞。 API 路徑 /addNewEmployee 包含了操作 addNew 和資源名稱 Employee。

　　那麼怎樣算是正確的方式？

　　/companies 是一個很好的不包含操作的例子。但是問題來了，我們該怎樣告訴伺服器我們要進行的操作呢？新增，刪除，還是更新？

　　這時 HTTP 方法（GET，POST，DELETE，PUT）（也稱為動詞）就可以起到作用了。

　　資源在 API 端點中應該總是複數，如果我們想訪問資源的一個例項，我們可以傳遞 URL 中的 id。

  • 方法 GET 路徑 /companies 是獲取所有公司的列表。

  • 方法 GET 路徑 /companies/34 是獲取公司34的詳細資訊。

  • 方法 DELETE 路徑 /companies/34 是刪除公司34.

　　在其他的一些使用案例中，如果我們有一些資源在某個資源之下，例如，一個公司的員工，那麼在這樣的例子中 API 的 endpoint（端點） 就應該是這樣的：

  • GET /companies/3/employees 可以取得編號為3的公司的員工列表

  • GET /companies/3/employees/45 可以取得編號為3的公司的45號員工的細節資訊

  • DELETE /companies/3/employees/45 可以刪除編號為3的公司的45號員工

  • POST /companies 可以建立一個新公司並返回新建立公司的細節資訊

　　現在這樣，API 是不是更嚴謹和一致了呢？

　　結論：路徑應該包含資源的複數形式，HTTP 方法應該定義成各種行為在資源上執行。

　　3) HTTP 方法 (動詞)

　　HTTP 定義了幾組方法，這些方法給出了對資源要執行的操作型別。

URL 是一個句子，其中資源是名詞，HTTP 方法是動詞。

　　主要的HTTP方法如下： 

  1. GET 方法從資源請求資料，不產生多餘結果。
    例如： /companies/3/employees 會返回公司3的所有僱員列表。

  2. POST 方法請求伺服器在資料庫中建立資源，這主要用於提交 Web 表單時。
    例如： /companies/3/employees 建立一個公司3的新僱員。 
    POST 是非冪等的，這意味著多個請求將會有不同的效果。

  3. PUT 方法請求伺服器更新資源或建立資源（如果不存在的話）。
    例如： /companies/3/employees/john 將請求伺服器在公司3的僱員集合中更新或在不存在的情況下建立關於 john 的資源。
    PUT 是冪等的，這意味著多次請求具有相同的效果。 

  4. DELETE 方法將請求的資源或例項從資料庫中刪除。
    例如： /companies/3/employees/john/ 將請求伺服器從公司3的僱員集中刪除 john 資源。

　　HTTP 中還有很多其他方法，我們將在另一篇文章中討論。

　　4) HTTP 響應狀態碼

　　當客戶端通過 API 向伺服器發起請求時，無論請求是失敗的、通過的還是錯誤的，客戶端應該獲得反饋。HTTP 狀態碼是一堆標準化的數值碼，在不同的情況下具有不同的解釋。伺服器應始終返回正確的狀態碼。

　　以下是 HTTP 狀態碼的主要分類：

　　2xx (成功類別)

　　這些狀態程式碼表示請求的操作已被伺服器接收到併成功處理。

  • 200 Ok：標準的 HTTP 響應，表示 GET、PUT 或 POST 的處理成功。

  • 201 Created：在建立新例項時，應返回此狀態程式碼。例如，使用 POST 方法建立一個新的例項，應該始終返回 201 狀態碼。

  • 204 內容不存在：表示請求已被成功處理，但並未返回任何內容。

　　DELETE算是其中一個很好的例子。

　　API DELETE /companies/43/employees/2 將刪除員工 2，作為響應，我們不需要在該 API 的響應正文中的任何資料，因為我們明確地要求系統將其刪除。如果有任何錯誤發生，例如，如果員工 2 在資料庫中不存在，那麼響應碼將不是 2xx 對應的成功類別，而是 4xx 客戶端錯誤類別。

　　3xx (重定向類別)

  • 304 未修改：表示客戶端的響應已經在其快取中。 因此，不需要再次傳送相同的資料。

　　4xx (客戶端錯誤類別)

　　這些狀態程式碼表示客戶端發起了錯誤的請求。

  • 400 錯誤請求：表示客戶端的請求沒有被處理，因為伺服器不能理解客戶端請求的是什麼。

  • 401 未授權：表示客戶端不被允許訪問該資源，需要使用指定憑證重新請求。

  • 403 禁止訪問：表示請求是有效的並且客戶端已通過身份驗證，但客戶端不被允許以任何理由訪問對應頁面或資源。 例如有時授權的客戶端不被允許訪問伺服器上的目錄。

  • 404 未找到：表示所請求的資源現在不可用。

  • 410 資源不可用：表示所請求的資源後續不再可用，該資源已被移動。

　　5xx（伺服器錯誤類別）

  • 500是伺服器內部錯誤，表示請求已經被接收到了，但伺服器被要求處理某些未預設的請求而完全混亂。

  • 503服務不可用表示伺服器已關閉或無法接收和處理請求。大多數情況是伺服器正在進行維護。

　　5) 欄位套管約定

　　您可以遵循任何套管約定，但要確保其在應用程式中一致。如果請求主體或響應型別是JSON，那麼請按照camelCase(駝峰命名法)來保持一致。

　　6) 搜尋、排序、過濾和分頁

　　這些行為都只是針對一個資料集進行的查詢。由於還沒有一套新的 API 來處理這些行為。因此，我們需要向 GET 方法的 API 附加查詢引數。

　　我們來理解幾個例子看它們是如何實現這些行為的。

  • 排序(sorting)，客戶端想要獲得排序後的公司列表，GET /companies 端點應當接受多個查詢排序引數。
    例如，GET /companies?sort=rank_asc 將根據等級以升序的方式對公司進行排序。

  • 過濾（Filtering），用來過濾資料集，我們可以通過查詢引數傳遞不同的選項。
    例如，GET /companies?category=banking&location=india 將根據公司類別為銀行以及所處位置為印度來過濾公司的列表資料。

  • 搜尋（Searching），當需要在公司列表中搜尋公司名稱時，API 端點應當是 GET /companies?search=Digital Mckinsey。

  • 分頁（Pagination），當資料集太大時，我們將資料集分成更小的塊，這樣有助於提高效能，並且更易於處理響應。 例如，GET /companies?page=23 表示獲取第 23 頁的公司列表。

　　如果在 GET 方法中附加了很多查詢引數，會造成 URI 太長，伺服器可能會響應 414 的 HTTP 狀態，表示這個 URI 太長，在這種情況下，我們也可以將引數傳遞給 POST 方法的請求體中。

　　7) 版本控制

　　當你的 API 被開始被廣泛使用後，突然升級API會打破現有的產品、服務。

　　http://api.yourservice.com/v1/companies/34/employees 是一個很好的例子，它的路徑中有API的版本號。如果有任何重大的中斷更新，我們可以將新的API集命名為v2或v1.x.x

　　這些指南是根據我的開發經驗編寫的。我很想知道你對上述幾點的看法。

　　原文地址：https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9#.8ljc9wpu4

相關文章