API 設計的最佳實踐

優秀的API設計話題，在很多團隊湧現，這些團隊正在努力完善他們的API政策。

在之前釋出的部落格上，我簡要的讨論了API設計的重要性。一個設計良好的API應該包含那些好處：你的API應該能提高開發者經驗、友善的快捷文檔和高可用性。

但優秀的API設計究竟應該怎麼做？在這個部落格中，我将詳細的介紹一些RESTful  API的最佳設計。 

一個設計良好的API的特點

一般來說，一個有效的API設計遇有以下特點：

• 易于閱讀和使用。一個設計良好的API應該很容易被使用，其資源和相關操作能夠快速的被使用它的開發人員記憶。
• 難以誤用。設計良好的API實作和內建将是個簡單的過程，寫出錯誤代碼将變得不太可能。沒有嚴格按照API開發指南的終端使用者将會得到詳實的資訊回報。

• 完整又簡潔. 最後，一個完整的API應該具有成熟的應用防止你的資料被洩露。API完整性會随着時間的推移而改變，大多數的API設計人員和開發人員都應在現有基礎上逐漸建構新的API。這是每一個使用API的工程師或公司都必須堅持的理念。

  為說明下面列出的概念， 我會以一個照片分享的應用程式舉例。 該應用程式允許使用者上傳照片， 以拍攝地點和心情标簽描述照片特征。

  集合，資源及其網址

  了解資源和集合

  資源是REST概念的基礎。 一條資源是一個重要對象，它本身可以被引用。 一條資源含有資料，與其他資源的關系，以及操作方法，以允許通路和處理相關資訊。

  名詞化的URL更好

  URL應該是整潔、優雅和簡單的，這樣開發人員更易在他們的web程式中使用你的産品。 很長且難以了解的URL不僅看起來很糟糕，而且在記錄時容易出現錯誤。是以使用名詞應該是很好的。

  沒有規定讓資源名詞使用單數或複數，但是在如果是集合的話使用複數無疑很好的。 具有相似的資源和集合分别保持它們的一緻性是較好的做法。

  REStful APIs包含主要的HTTP方法，其良好的定義和獨立的功能能夠應對所有資源。這裡是RESTful API裡常用HTTP方法清單，這些方法定義CRUD如何操作資源和集合。

  方法	描述
  GET	用于請求檢索一個資源
  POST	用于建立新資源和子資源
  PUT	用于更新已存在的資源
  PATCH	用于更新已存在的資源
  DELETE	用于删除已存在的資源

  (如果你想了解PUT和PATCH的不同，可以到StackOverflow上看看這個.)  良好的回報對于實作的驗證是積極的，錯誤實作産生的消息可以幫助使用者調試和糾正使用産品的不正确方式。對于API, 錯誤資訊是使用API上下文的良好方式之一。

  調整你的錯誤與标準HTTP代碼一緻。用戶端引發的錯誤應該使用400類型錯誤，如果是服務端的錯誤應該使用500類型來響應。 一個對資源操作成功後應該傳回一個200類型的響應。

  有很多的響應代碼。想了解更多, 看看這個REST API教程.

  一般來說，使用你的API時有三種可能就結果：

  1. 用戶端應用程式的行為是錯誤的(用戶端錯誤–4xx響應代碼)
  2. API行為錯誤 (伺服器錯誤- 5 xx響應代碼)
  3. 用戶端和API工作正常 (成功– 2xx響應代碼)
  成功解決客戶使用你的API時遇到的問題将大大改善開發人員使用體驗和防止濫用API。 較長的描述這些錯誤，同時保持簡明和整潔。在錯誤消息中提供足夠的資訊有助于使用者解決它們的問題，如果你覺得需要更加詳細的資訊，最好另寫文檔并在此處提供連結。  

   GET 響應例子

  一個良好設計的API應該有響應示例，以明白是否成功調用了一個URL。響應示例應該簡單、簡潔和易于了解的。 一個好的經驗法則是：幫助開發人員在5秒内了解一個成功的響應。回到我們的照片分享應用，我們定義了 /users 和 /photos URL。 /users 應該易數組的形式提供所有注冊的使用者，并且包含使用者名稱和加入日期屬性。

  你可以在Swagger（OpenAPI）中使用 API設計工具 來定義你的API，詳述如下：

  responses:
          :
            description: Successfully returned information about users 
            schema:
              type: array
              items:
                type: object
                properties:
                  username:
                    type: "string"
                    example: "kesh92"
                  created_time:
                    type: "dateTime"
                    example: "2010-01-12T05:23:19+0000"
             

  注意資料類型和執行個體的每個響應項注釋，最終使用者期望的是一個成功的GET調用。成功響應後最終使用者将接收的JSON看起來如下

  {
     “data”:[
        {
           “Username”:“example_user1”,
           “created_time":“2013-12-23T05:51:14+0000         ”
        },
        {
           “username”:“example_user2”,
           “created_time":“T17:51:15+0000         ”
        }
  ….
     ]
  }
             

  如果使用者調用了這個方法，就應該獲得包含上述資料和一個說明正确調用了的200響應狀态碼。 同樣的,，一個不正确的調用應該産生适當的400 或500 響應狀态碼和其它相關資訊，以幫助使用者更好地操作。

  請求

  優雅的處理複雜性

  你試圖開放的資料包含大量的有利于使用者的屬性，這些屬性描述的基本資源和隔離特定資訊，可以通過适當的方法來操作。

  一個API應該努力提供完整的資訊、資料和資源來幫助開發者以無縫的方式與之整合。

  然而， 完整意味着對你的API考慮通用使用情況。可能會有許多這樣的關系和屬性,單獨為他們定義資源不是好的做法。

  它可以用于開發者擷取在特定位置和特定主題标簽中共享的所有照片的資訊。 您可能還想要通過将每個 API 調用的結果數限制為 10，以減輕伺服器負載。 如果最終使用者想要找到波士頓的所有照片，并使用 winter 标簽，則請求将是：

  GET /photos?location=boston&hashtag=winter&limit=10
             

  注意現在的複雜性如何被簡化為一個與查詢參數的簡單關聯。如果您想根據客戶的請求提供特定使用者的資訊，則調用：

  API設計入門

  沒有一個API設計方法能夠一勞永逸解決所有組織的問題。上述的建議僅僅是參考意見和建議，能否采用取決于你的使用者情況和需求。

  一個API設計至關重要的主要原因是你的API能幫助到終端使用者，他們的需求就是貫穿你整個API設計的指明燈。

  • 作者：Keshav Vasudevan
  • 連結：http://coyee.com/article/11302-good-practices-in-api-design
  文章來源:https://coyee.com/article/11302-good-practices-in-api-design#comments