非 RESTful 的微軟 REST API 指南

微軟釋出了建立“restful” api的指南。roy fielding将這些與rest沒有多大關系的api稱為http api。

許多組織都釋出了建立面向web的http api的建議，甚至是白宮都釋出了一份标準——“白宮web api标準”。近日，微軟公開了他們的“微軟rest api指南2.3”，這是一份全面而成熟的規範。該規範被制定出來，主要是供azure團隊在建構雲服務時使用。

下面總結了微軟api指南的一些關鍵點，感興趣地讀者可以閱讀完整的規範。

為了便于api的應用，url應該是人類可讀和可構造的，而不必借助用戶端庫。

應支援以下http謂詞：get、put、delete、post、head、patch、options。不是所有的資源都應該支援所有的謂詞。

get、put、delete和head應該是幂等的。

自定義頭資訊不是必須的。

用戶端應該不需要在url中傳遞個人身份資訊參數，因為它們可能會暴露在日志檔案中。參數應該通過頭資訊傳遞。

資料應該以流行的格式提供。

預設資料編碼是json。

“基本型數值必須遵循rfc4627标準序列化成json。”

使用api的開發人員應該能夠使用喜歡的語言和平台。

即使是簡單的http工具，如curl，也應該能夠通路服務。

api應該支援顯式版本。

服務應該保持穩定，如果可能，就不要引入破壞性修改，但如果必要，它們也應該允許這樣做，通過增加版本号辨別出來。

版本應該使用一種major.minor方案。

服務可以通過web鈎子（http回調）實作推送通知。

該指南提供了一個例子，說明了什麼樣的url是結構良好的url:

而另外一個例子說明了什麼樣的url是應該避免的：

roy fielding是rest及http/1.1的作者，同時也是apache基金會的聯合創始人。在微軟釋出這份rest api指南之後不久，他就表達了對這份規範的不滿：“即使是我最糟糕的rest描述也比[微軟/aip指南]提供的總結或參考要好很多。”infoq聯系了fielding，更詳細地了解他為什麼對這份規範不滿意。以下是他的完整回複：

我認為，像微軟這樣的公司決定将部分内部文檔和開發指南釋出到公共論壇，尤其是像github這樣的開源協作空間，是很好的。對于公共對話的這種開放性将極大地改善我們這個行業的工作方式。

對于這份指南，我不滿意的是，這份指南明明是總結了如何在微軟的生态系統中開發合理的http api，但卻冠以rest和restful api的标簽。rest不等于http，這是顯而易見的，粗略地讀下任何有關rest的資料就可以知道。這份指南明顯不是基于rest的，他們甚至沒有設 法參考我的工作（除了已經被rfc7231廢除的rfc2616的部分内容）。對于以前深入web services世界的人們，這是一個常見的錯誤：将rest描述成soap/rpc接口的某種http版本。

不管那種錯誤在實際中多麼常見，它都不能自稱是rest。rest架構風格的大部分屬性都源于對其所有限制的堅持，而不隻是那些與過去已失敗的 工具類似的限制。如果那些想要使用http建構rpc接口的人們，将它們的接口稱為http api，那麼我沒有任何意見。它們不是rest的。它們不屬于web。那并不是說，它們不能被誠實地描述，并實作為http服務。要這樣了解它們，讨論它 們的實作指南，而又不覺得需要遵從錯誤的說法，這是值得的。

許多web服務提供商都使用了http api，并且運用得非常成功。大部分雲計算都是基于這樣的api。不知道為什麼這麼多人堅持把它們的服務稱為“restful”，而它們并不是。關于這個問題，我們建議那些有興趣了解更多資訊的讀者閱讀下列infoq文章：《為什麼有些web api不是restful的？針對這些api我們能做些什麼？》、《與roy fielding談論版本化、超媒體以及rest》。

檢視英文原文：microsoft rest api guidelines are not restful