API設計指南 RestAPI設計最佳實踐

類似於阿里巴巴的開發規範或者谷歌的開發規範，api設計是目前很多場景下的基本功，所以這裡給出乙個筆者的最佳實踐。

rest，即representational state transfer的縮寫，關於restful架構，可以參考《架構之美》中的定義。

get: 獲取資源

post: 更新資源

put: 更新資源

delete: 刪除資源

api與客戶端通訊的協議，應該盡量使用https。除此之外，白名單機制、vpn可以提高更高的安全性。遵循「所有人應該知道他所需要完成工作必備的最少的知識」的原則。而乙個介面，只有在訪問者必須使用它時，才告訴這個訪問者。

應該將api部署到專用網域名稱之下，好處顯而易見。

示例：

更好的實踐是將服務分組，並且根據情況進行必要的層次和分組(group)。這裡的group可以包含事業部，也可以包含不同的客戶，更可以包含不同的層次。

規範：https://api.[service-group].domain.io/

基本的url，在此文中指的是除了服務拆分之外的url，這裡的最佳實踐是可以包含環境、版本、分類、層次等，但是乙個基本的url，已經能決定除了介面或者服務粒度以外的所有事情，或者說可以決定由乙個作戰單元（個人或者小的敏捷團隊）日常維護的工作內容了。

示例：

整體服務架構的劃分原則不在此文件討論範圍之內，而乙個最佳實踐是在domain當中就對環境作區分。

規範：https://api-[env-name].groupname.domain.io/

應該將api的版本號放入url合適的層次。注意這裡的version既不表示客戶端的版本，也不表示伺服器中服務對應的版本，而是特指該介面的版本。一般用來處理對介面進行公升級的情況。

規範：https://api-[env-name].groupname.domain.io/mobile/[version]/

提供以下原則供參考：路徑表示api的具體url，每乙個url唯一的表示一種資源，所以**中不應該有動詞，只應該有名詞，而且所用的名詞往往與代表的物件名稱對應，一般來說是某一種記錄的集合，所以api名詞當中應該使用複數。

以下括號中對應sql的動詞：

最佳實踐

一般有如下建議：

api應該提供引數，過濾返回結果。因為伺服器端某個資源數量可能很多，比如使用者的訂單數、全國的酒店數等。過濾的語義應該包括對資料集合的過濾、排序、選擇和分頁等功能。

最佳實踐

如果狀態碼不是正確的返回，就應該返回出錯資訊，盡量使用詳細的錯誤資訊，乙個好的實踐是出錯資訊應該包含：

get /collection：返回資源列表

get /collection/resource：返回單個物件

post /collection/resource：返回新生成的物件

put /collection/resource：返回完整的更新後的資源物件

patch /collection/resource：返回完整的更新後的資源物件

delete /collection/resource：返回乙個空文件

乙個好的hypermedia範例是：

", "commit_search_url": "search/commits?q=", "emails_url": "user/emails", "emojis_url": "emojis", "events_url": "events", "feeds_url": "feeds", "followers_url": "user/followers", "following_url": "user/following", "gists_url": "gists", "hub_url": "hub", "issue_search_url": "search/issues?q=", "issues_url": "issues", "keys_url": "user/keys", "label_search_url": "search/labels?q=&repository_id=", "notifications_url": "notifications", "organization_url": "orgs/", "organization_repositories_url": "orgs//repos", "organization_teams_url": "orgs//teams", "public_gists_url": "gists/public", "rate_limit_url": "rate_limit", "repository_url": "repos//", "repository_search_url": "search/repositories?q=", "current_user_repositories_url": "user/repos", "starred_url": "user/starred", "starred_gists_url": "gists/starred", "user_url": "users/", "user_organizations_url": "user/orgs", "user_repositories_url": "users//repos", "user_search_url": "search/users?q="

}

標準的請求定義當中有很多最佳實踐，比如content-type等。好的實踐是我們盡早用較小的代價將content-type、language等加入設計當中，可以避免後續很多問題。

認證的時候取決於api的使用者和生產者之間的關係以及需要保護的程度，目前此處的最佳實踐是採用oauth 2.0當中合適的模式來構建。

使用 swagger api+json 進行文件管理和資訊描述，定義乙個標準的、語言無關的、供人和計算機理解服務的文件，類似於soap當中的wsdl。

可以用於api設計review。

方便測試人員了解api定義。

可以作為客戶產品文件的一部分進行發布。

可以通過api swagger文件生成使用者和生產者的骨架**。

API設計指南 RestAPI設計最佳實踐

API設計 RESTful API 設計指南

筆記 REST API 設計

REST API設計規範

API設計指南 RestAPI設計最佳實踐

API設計 RESTful API 設計指南

筆記 REST API 設計

REST API設計規範

相關推薦