Microsoft REST API指南

序言

经过3个月的碎片时间的翻译和校验，由长沙.NET技术社区翻译的英文原文文档《Microsoft REST API指南》已经翻译完成，现刊载前十一章如下，欢迎大家点击“查看原文”按钮，查看指南的完整内容。

PS：内容很长，全文读完大概需要耗时100分钟。

Microsoft REST API指南工作组

Name	Name	Name
Dave Campbell (CTO C+E)	Rick Rashid (CTO ASG)	John Shewchuk (Technical Fellow, TED HQ)
Mark Russinovich (CTO Azure)	Steve Lucco (Technical Fellow, DevDiv)	Murali Krishnaprasad (Azure App Plat)
Rob Howard (ASG)	Peter Torr (OSG)	Chris Mullins (ASG)

Document editors: John Gossman (C+E), Chris Mullins (ASG), Gareth Jones (ASG), Rob Dolin (C+E), Mark Stafford (C+E)

感谢.NET长沙社区提供的翻译，感谢译者李文强，译者周尹

本文首发 .NET社区公众号，欢迎关注, 搜索 MoreDotNetCore ,里面有最新的原创性资讯，获得第一手的资料。

摘要

Microsoft REST API指南作为一种设计原则，鼓励应用程序开发人员通过RESTful HTTP接口访问资源。

文档原则认为REST API应该遵循一致的设计指导原则，能为开发人员提供最流畅的体验，令使用它们变得简单和直观。

本文档建立了Microsoft REST API应该遵循的指导原则，以便统一一致的开发RESTful接口。

引言

开发人员通常通过HTTP接口访问大多数微软云平台资源。虽然每个服务通常提供特定于语言框架来包装其API，但它们的所有操作最终都归结为HTTP请求。微软必须支持广泛的客户端和服务，不能依赖于每个开发环境都有丰富的框架。因此，本指导原则的目标是确保Microsoft REST API能够被任何具有基本HTTP支持的客户端轻松且一致地使用。

[*]译者注：本指南不限于微软技术和平台，广泛适应于各种语言和平台。

为了给开发人员提供最流畅的体验，让这些API遵循统一的设计准则是很重要的，从而使其简单易用，符合人们的直觉反应。本文档建立了 Microsoft REST API 开发人员应该遵循的指南, 以便统一一致地开发API。

一致性的好处在于可以不断地积累合理的规范;一致性使团队拥有统一的代码、模式、文档风格和设计策略。

这些准则旨在达成如下目标：

为Microsoft技术平台所有API端点定义一致的实现和体验。
尽可能地遵循行业普遍接受的 REST/HTTP 最佳实践。
让所有应用开发者都可以轻松的通过REST接口访问Micosoft服务。
允许Service开发者利用其他Service的基础上来开发一致的REST API端点。
允许合作伙伴(例如,非Micosoft团队)使用这些准则来设计自己的 REST API。

[*]注：本指南旨在构建符合 REST 架构风格的服务，但不涉及或要求构建遵循 REST 约束的服务。

本文档中使用的“REST”术语代指具有 RESTful风格的服务，而不是仅仅遵循 REST。

4. 解读指导

4.1 应用指南

这些准则适用于Microsoft或任何合作伙伴服务公开的任何REST API。私有或内部API也应该尝试遵循这些准则，因为内部服务最终可能会被公开。保证一致性不仅对外部客户有价值，对内部服务使用者也很有价值，而这些准则为对任何服务都提供了最佳实践。

有合理理由可不遵循这些准则。如：实现或必须与某些外部定义的REST API互操作的REST服务必须与哪些外部的API兼容，而无法遵循这些准则。而还有一些服务也可能具有需要特殊性能需求，必须采用其他格式，例如二进制协议。

4.2 现有服务和服务版本控制的指南

我们不建议仅仅为了遵从指南而对这些指南之前的旧服务进行重大更改。无论如何，当兼容性被破坏时，该服务应该尝试在下一版本发布时变得合规。

当一个服务添加一个新的API时，该API应该与同一版本的其他API保持一致。

因此，如果服务是针对 1.0 版本的指南编写的，那么增量添加到服务的新 API 也应该遵循 1.0 版本指南。然后该服务在下一次主要版本更新时，再去遵循最新版指南。

4.3 要求语言

本文档中的”MUST”（必须）, “MUST NOT”（禁止）, “REQUIRED”（需要）, “SHALL”（将要）, “SHALL NOT”（最好不要）, “SHOULD”（应该）, “SHOULD NOT”（不应该）, “RECOMMENDED”（推荐）, “MAY”（可能）, 和 “OPTIONAL”（可选）等关键字的详细解释见 RFC 2119。

4.4 许可证

本作品根据知识共享署名4.0国际许可协议授权。如需查看本授权的副本，请访问http://creativecommons.org/licenses/by/4.0/ 或致函 PO Box 1866, Mountain View, CA 94042, USA.

》 [*]译者注：署名 4.0 国际，也就是允许在任何媒介以任何形式复制、发行本作品，允许修改、转换或以本作品为基础进行创作。允许任何用途，甚至商业目的。

5. 分类

作为Microsoft REST API指南的一部分，服务必须符合下面定义的分类法。

5.1 错误

错误，或者更具体地说是服务错误，定义为因客户端向服务传递错误数据，导致服务端拒绝该请求。示例包括无效凭证、错误的参数、未知的版本ID等。客户端传递错误的或者不合法的数据的情况通常返回 “4XX” 的 HTTP 错误代码。

错误不会影响API的整体可用性。

[*]译者注：错误可以理解成客户端参数错误，通常返回“4XX”状态码，并不影响整体的API使用。

5.2 故障

故障（缺陷），或者更具体地说是服务故障，定义为服务无法正确返回数据以响应有效的客户端请求。通常会返回“5xx”HTTP错误代码。

故障会影响整体 API 的可用性。

由于速率限制（限流）或配额故障而失败的调用不能算作故障。由于服务快速失败(fast-failing)请求(通常是为了保护自己)而失败的调用会被视为故障。

[*]译者注：故障意味着服务端代码出现故障，可能会影响整体的API使用。比如数据库连接超时。

fast-failing 快速失败

safe-failing 安全失败

5.3 延迟

延迟定义为特定的API调用完成所需的时间(尽可能使用客户端调用进行测量)。此测量方法同样适用于同步和异步的API。对于长时间运行(long running calls)的调用，延迟定义为第一次调用它所需的时长，而不是整个操作)完成所需的时间。

[*]译者注：Latency（延迟）是衡量软件系统的最常见的指标之一，不仅仅和系统、架构的性能相关，还和网络传输和延迟有关系。

5.4 完成时间

暴露长时间操作的服务必须跟踪这些操作的 “完成时间” 指标。

5.5 长期运行API故障

对于长期运行的 API，很可能出现第一次请求成功，且后续每次去获取结果时 API 也处于正常运行（每次都回传 200）中，但其底层操作已经失败了的情况。长期运行故障必须作为故障汇总到总体可用性指标中。

6. 客户端指导

为确保客户端更好的接入REST服务，客户端应遵循以下最佳实践:

6.1 忽略规则

对于松散耦合的客户端调用，在调用之前不知道数据的确切定义和格式，如果服务器没用返回客户端预期的内容，客户端必须安全地忽略它。

在服务迭代的过程中，有些服务（接口）可能在不更改版本号的情况下向响应添加字段。此类服务必须在其文档中注明，客户端必须忽略这些未知字段。

[*]译者注：一个已发布的在线接口服务，如果不修改版本而增加字段，那么一定不能影响已有的客户端调用。

6.2 变量排序规则

客户端处理响应数据时一定不能依赖服务端JSON响应数据字段的顺序。例如，当服务器返回的 JSON 对象中的字段顺序发生变化，客户端应当能够正确进行解析处理。

当服务端支持时，客户端可以请求以特定的顺序返回数据。例如，服务端可能支持使用$orderBy querystring参数来指定JSON数组中元素的顺序。

服务端也可以在协议中显式说明指定某些元素按特定方式进行排序。例如，服务端可以每次返回 JSON 对象时都把 JSON

对象的类型信息作为第一个字段返回，进而简化客户端解析返回数据格式的难度。客户端处理数据时可以依赖于服务端明确指定了的排序行为。

6.3 无声失效规则

当客户端请求带可选功能参数的服务时（例如带可选的头部信息），必须对服务端的返回格式有一定兼容性，可以忽略某些特定功能。

[*]译者注：例如分页数、排序等自定义参数的支持和返回格式的兼容。

7. 基础原则

7.1 URL结构

URL必须保证友好的可读性与可构造性，人类应该能够轻松地读取和构造url。