微軟發布了創建“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:

https://api.contoso.com/v1.0/people/[email protected]/inbox

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

https://api.contoso.com/EWS/OData/Users('[email protected]')/Folders('…[very long identifier]…=')

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