非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:

https://api.contoso.com/v1.0/people/jdoe@contoso.com/inbox

而另外一个例子说明了什么样的URL是应该避免的：

https://api.contoso.com/EWS/OData/Users(jdoe@microsoft.com)/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》。

====================================分割线================================

本文转自d1net（转载）

分布式系统核心：REST风格的架构，REST成熟度模型及REST API管理 正如前文所述，正确、完整地使用REST是困难的，关键在于RoyFielding所定义的REST只是一种架构风格，它并不是规范，所以也就缺乏可以直接参考的依据。好在Leonard Richardson补充了这方面的不足。
国王小组：数字货币交易所开发中Binance REST API接入方式 秒合约交易所开发详细丨秒合约交易所系统开发详细及规则丨秒合约交易所系统源码部署 数字货币交易所开发源码丨数字货币交易所系统开发（详细及逻辑） 交易所开发正式版丨区块链交易所系统开发实现技术功能及源码 交易所开发案例丨交易所系统开发（详细及流程）丨交易所成熟及源码系统 交易所开发（稳定版）丨交易所系统开发（方案及逻辑）丨 交易所系统源码功能 什么是去中心化交易所系统开发丨浅谈uniswap丨justswap 交易所源码（整体架构演示） 交易所搭建，交易所源码是怎么开发的？ 区块链交易所怎么搭建？ 区块链交易所平台中常见的开发模式有哪些？ 区块链交易所如何开发（介绍区块链应用开发的流程）
9个REST API设计的基本准则 通常情况下，在项目开发过程中涉及的API设计是采用REST API的模式，但并没有制定一个严格的、可理解的、可扩展的规范，从长远来看，随着项目的不断迭代，特别的在赶工期的情况下，REST API就会出现偏移。因此建议在项目初期就建立严格的API设计规范。
GraphQL与REST：两种API架构 在过去十年中，REST已经成为Web API的设计标准，提供了一些很棒的想法，例如无状态服务器和对资源的结构化访问，可以去这里详细了解REST API。但是，REST API已经显示出太不灵活，无法满足访问客户端快速变化的需求。