GOTO Berlin: Web API設計原則

在郵件列表和討論區中有不少與REST和Web API相關的討論，下面僅是我我的對這些問題的一些看法，並無絕對的真理，InnoQ的首席顧問Oliver Wolf在GOTO Berlin大會上開始本身的演講「Web API設計原則」時如是說。

不要考慮端點。SOAP有一個單獨入口點的外觀。相比之下Web有不少入口點，它們創建在關係上，彼此之間相互鏈接，而且以超媒體做爲關鍵要素。爲了避免讓你的API成爲一個只有一種接入方式的黑洞，你應該使用超媒體控制按照對聽衆有意義的表現方式去連接你的資源。

不要在API中暴露領域模型。在不少模型中存在的一個問題即是它們僅包含數據，缺少全部形式的行爲，也就是所謂的貧血模型（anaemic model）。若是你暴露這樣一個模型，那麼最終將會成爲CRUD（建立、讀取、更新和刪除）和資源。這並不必定是一件壞事，有時你所須要的全部內容即是一個純粹的CRUD API。不然暴露一個CRUD模型的問題即是，使用這樣一個API的客戶端須要瞭解不少知識，清楚它可以對哪些資源執行什麼操做，按照什麼樣的順序執行等等這些內容。大量的邏輯須要編碼在客戶端中，使得客戶端和服務器之間變得緊耦合。

目的明確以後再設計API。想一想你的客戶端想要作什麼，如何作。有時這須要在清晰度和靈活性之間權衡，你須要多麼簡單清晰的API，須要什麼程度的靈活性。一種靈活可是也更加迫切的獲取最有利可圖的客戶的方式是：

GET /customers?sortBy=grossmargin&order=descending

相比之下，下面是一種聲明意味更濃的暴露意圖的方式，可是也缺少靈活性：

GET /most_profitable_customers

Oliver提到這裏須要注意的一點是，考慮一下客戶端須要使用你的API作什麼，它的意圖應該是什麼，並儘可能讓它完美契合這些須要。

不要過分使用GET和POST。這基本上意味着你不該該按照錯誤的方式使用它們，也不能違反HTTP規範。例如，你不該該使用GET或者POST刪除資源。每一個HTTP動詞的產生都有各自的緣由，它們之間是互補的，經過擁抱規範你獲得的將會更多。使用動詞傳達目的，客戶端想要作什麼，它們指望從服務器獲得哪些行爲。

不要將錯誤碼的選擇限制爲200和500。使用完整範圍的錯誤碼，有160個錯誤碼供你選擇，因此幾乎每一種類型的錯誤都有一個對應的錯誤碼。使用正確的錯誤碼是客戶端可以合理處理錯誤的關鍵。一個常見的問題是，儘管發生了一個錯誤可是服務器依然返回200，OK。在這種事情發生時僞裝全部事情運行良好顯然不是一個很好的想法。

不要忽略緩存。 不管涉及到什麼都會有緩存，它是Web的一個很是重要的部分。若是你不想使用緩存，那麼經過添加合適的緩存頭明確地關閉它。
一種比較好的控制緩存的方式是使用驗證器，最好是Etags。它們容許服務器端操做任意的數據，一個Etag僅僅是服務器生成並傳入緩存的一個值，而後緩存會將其傳回以詢問服務器是否有更新的資源。

不須要版本。一般狀況下，當資源發生變化的時候實際上它僅僅是展現發生了改變，而它依然是那個資源，應該使用同一個URL，所以避免將URL版本化。相反的，應該有一個新版本的媒體類型，例如經過下面的方式添加版本v2：

Content-Type=application/vnd.company.v2+xml

不要對內容協商使用擴展。協商一種表現格式的正確方法是在消息頭中使用Accept和Content-Type。

2013年的GOTO Berlin大會是GOTO大會首次在Berlin舉行，本次大會有超過400位參會者和大約80位講師。

查看英文原文：GOTO Berlin: DO’s and DON’Ts in a Web API