Web API 設計摘要

近期讀了一本微電子書 Brian Mulloy 所著《Web API Design》感受頗多收穫，特對其內容作了個整理摘要以便回想其觀點精華以指導平常工做中的設計思路。

本文主要講述 Web API 設計，追求一種更務實的 REST 風格。 正如做者所說 REST 是一種架構風格，而非嚴格的標準，不是必需在形式定義上去作過多真論，究竟什麼纔是真正的 REST？ 設計的目的是爲了表達某樣東西是怎樣使用的，那麼 API 設計的成功與否是由開發者是否能夠高速上手並用的愉快。

如下講述了 Web API 設計的 13 個要點。

本條是關於 URL 設計的，使用名詞而非動詞，讓 URL 保持簡單和符合直覺。
這條是針對資源型 URL 設計而言，爲何？請看下一條。

用名詞表達來領域概念，可以極大的下降 URL（API）的需求量。
使用 HTTP 協議方法動做來操做領域概念集。
經過分離概念和行爲極大簡化了 API 設計，讓 URL 中僅僅體現概念而非行爲。

/elements/elementId 的二級 URL 形式，第一級表達元素集合，第二級表達集合中某個詳細元素 id，所以使用名詞複數是做者推薦的更符合認知直覺的方法。 同一時候對於元素集合使用更詳細的領域名詞含義更清晰，若使用抽象的概念名詞則表達不清。

爲了表達對象間的關聯性，有一種方法是體現在 URL 的層級中，但 URL 層級過深並不便於記憶和認知。 這裏推薦用 HTTP '?' 後可選參數來表達關聯條件，簡化 URL 複雜性。

假設可能使用 HTTP 的錯誤碼來映射 API 錯誤。 HTTP 自己已經定義了廣爲認知的錯誤碼區間，按類型將錯誤映射到相應區間對開發者的學習和認知更友好。 提供儘量詳盡的錯誤信息。

毫不公佈一個不帶版本的 API。關於這點作過軟件維護的都明確，有一點細節就是版本號號的選擇，請使用 v1, v2 整數版本號號而非 v1.1 v1.2 這樣的帶小數點版本號號機制。這裏有個心理認知緣由，帶小數點的版本號一般給人的感受會頻繁變化，而對於一個開放的 API 而言頻繁變動絕對是應該避免的，所以不要使用帶小數點版本號號機制。

當我請求某個對象時不需要其全部屬性或需要分頁時怎麼辦？上圖中樣例已經很是好的回答了。

該條針對非資源型 URL 設計而言，因爲有些狀況就是請求作一個計算，如上圖中所看到的請求金額按幣種進行轉換。 對於此類 API，使用動詞就是合適的，但最好在你的 API 文檔中將此類 API 獨立分類說明。

開發者對文件系統的後綴名命名方式都很是熟悉了，所以使用後綴名錶達響應格式是天然的。 那麼默認格式應該選擇什麼呢？毫無疑問是 JSON，這一點與 javascript 是 Web 端的通用語言有關。

如上，既然咱們要照應 javascript 語言，那麼屬性命名天然也要採用 javascript 語言傳統的駝峯命名法。

簡單的搜索可以用資源型 API 來模式化，但全局的搜索 Google 模式你們都很是熟悉。

爲 API 申請獨立的子域名，有且僅有一個是最好的，而且最好是這個域名模式 api.youdomain.com




有了 API 還不夠，輔助以 SDK 工具包可以進一步減輕 API 使用者的負擔，最重要的是還能避免 API 的誤用和低效使用。 事實上這裏另外一個優勢：

Eating your own dog food