RESTful API設計指南-最佳實踐

Facebook，Google，Github，Netflix和其他少數技術巨頭給開發人員和產品提供了通過API使用數據的機會，併成爲了他們的平臺。
即使您沒有爲其他開發人員和產品編寫API，使用精心製作的API對於您的應用程序也總是非常健康。

關於設計API的最佳方法，互聯網上有很長的爭論，這是最細微的差別之一。沒有爲此定義任何官方指南。

API是一個接口，許多開發人員可通過該接口與數據進行交互。設計良好的API總是非常易於使用，並使開發人員的生活非常順利。API是開發人員的GUI，如果感到困惑或冗長，則開發人員將開始尋找替代方案或停止使用它。開發人員的經驗是衡量API質量的最重要指標。

API就像是藝術家在舞臺上表演，其用戶是觀衆

 

1）術語

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

• 資源是事物的對象或表示，它具有一些關聯的數據，並且可以使用一組方法對其進行操作。例如，動物，學校和僱員是資源，刪除，添加，更新是對這些資源要執行的操作。
• 集合是資源集，例如，公司是公司資源的集合。
• URL（統一資源定位符）是可用來定位資源並對其執行某些操作的路徑。

2）API端點

讓我們爲擁有一些員工的公司寫一些API ，以瞭解更多信息。
/getAllEmployees是一個將響應僱員列表的API。公司周圍的其他API 如下所示：

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

諸如此類的大量其他API端點將用於不同的操作。所有這些將包含許多多餘的動作。因此，當API數量增加時，所有這些API端點都將難以維護。

怎麼了？
該URL僅應包含資源（名詞）而不是動作或動詞。API路徑/addNewEmployee包含操作addNew 以及資源名稱Employee。

那正確的方法是什麼？
/companies端點是一個很好的示例，其中不包含任何操作。但是問題是我們如何告訴服務器要在companies資源viz 上執行的操作。是否添加，刪除或更新？

這就是HTTP方法（GET，POST，DELETE，PUT）（也稱爲動詞）發揮作用的地方。

該資源在API端點中應始終爲複數形式，並且如果我們要訪問該資源的一個實例，則可以始終在URL中傳遞ID。

• 方法GET路徑/companies應獲取所有公司的列表
• 方法GET路徑/companies/34應獲取公司的詳細信息34
• 方法DELETE路徑/companies/34應刪除公司34

在其他一些用例中，如果我們在某個資源下擁有資源，例如公司的僱員，則樣本API端點很少是：

• 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資源。

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

4）HTTP響應狀態碼

當客戶端通過API向服務器提出請求時，客戶端應該知道反饋，無論是失敗，通過還是請求錯誤。HTTP狀態代碼是一堆標準化代碼，在各種情況下都有各種說明。服務器應始終返回正確的狀態代碼。
以下是HTTP代碼的重要分類：

2xx（成功類別）

這些狀態碼錶示服務器已接收併成功處理了請求的操作。

• 200 Ok標準的HTTP響應，表示GET，PUT或POST成功。
• 201已創建每當創建新實例時，都應返回此狀態代碼。例如，使用POST方法創建新實例時，應始終返回201狀態代碼。
• 204 No Content表示請求已成功處理，但未返回任何內容。
  刪除就是一個很好的例子。
  API DELETE /companies/43/employees/2將刪除僱員2，並且作爲回報，我們明確要求系統刪除，因此API的響應正文中不需要任何數據。如果有任何錯誤（例如如果employee 2數據庫中不存在），則響應代碼將不是，2xx Success Category而是4xx Client Error category。

3xx（重定向類別）

• 304 Not Modified表示客戶端已經在其緩存中包含響應。因此，無需再次傳輸相同的數據。

4xx（客戶端錯誤類別）

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

• 400錯誤的請求表示客戶端的請求未處理，因爲服務器無法理解客戶端的要求。
• 401 Unauthorized表示不允許客戶端訪問資源，應使用所需的憑據重新請求。
• 403禁止表示請求有效且客戶端已通過身份驗證，但由於任何原因不允許客戶端訪問頁面或資源。例如，有時不允許授權的客戶端訪問服務器上的目錄。
• 找不到404表示請求的資源現在不可用。
• 410已消失表示已被有意移動的請求資源不再可用。

5xx（服務器錯誤類別）

• 500 Internal Server Error表示請求有效，但是服務器完全混亂，要求服務器提供某些意外條件。
• 503服務不可用表示服務器已關閉或無法接收和處理該請求。通常，如果服務器正在進行維護。

5）字段名稱大小寫約定

您可以遵循任何大小寫約定，但是請確保在整個應用程序中保持一致。如果請求正文或響應類型爲JSON，則請遵循camelCase保持一致性。

6）搜索，排序，過濾和分頁

所有這些動作僅是對一個數據集的查詢。沒有新的API集可以處理這些操作。我們需要在查詢參數中附加GET方法API。
讓我們用幾個示例來了解如何實現這些操作。

• 排序如果客戶想要獲得公司的排序列表，則GET /companies端點應在查詢中接受多個排序參數。
  例如，GET /companies?sort=rank_asc將按升序對公司進行排序。
• 過濾爲了過濾數據集，我們可以通過查詢參數傳遞各種選項。
  例如，GET /companies?category=banking&location=india將使用“銀行”的公司類別以及位置在印度的公司列表數據進行過濾。
• 搜索在公司列表中搜索公司名稱時，API端點應爲GET /companies?search=Digital Mckinsey
• 分頁當數據集太大時，我們將數據集分成較小的塊，這有助於提高性能並更容易處理響應。例如。GET /companies?page=23意味着在第23頁上獲得公司列表。

如果在GET方法中添加許多查詢參數會使URI太長，則服務器可能會以414 URI Too longHTTP狀態進行響應，在這種情況下，參數也可以在方法的請求主體中傳遞POST。

7）版本控制

當您的API受到全世界的歡迎時，以一些重大更改升級API還會導致使用您的API破壞現有的產品或服務。

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

這些準則是根據我的開發經驗編寫的。我很想知道您對上述指針的看法。請發表評論，讓我知道！