非 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