在郵件列表和討論區中有很多與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位講師。
文章列表
留言列表
