翻译自微软的Microsoft REST API Guidelines
Document editors: John Gossman (C+E), Chris Mullins (ASG), Gareth Jones (ASG), Rob Dolin (C+E), Mark Stafford (C+E)
The Microsoft REST API Guidelines, as a design principle, encourages application developers to have resources accessible to them via a RESTful HTTP interface.
作为设计原则，Microsoft REST API 指南鼓励程序开发人员通过 RESTful HTTP 接口访问获取资源。
To provide the smoothest possible experience for developers on platforms following the Microsoft REST API Guidelines, REST APIs SHOULD follow consistent design guidelines to make using them easy and intuitive.
为了给遵循 Microsoft REST API 指南的平台上的开发者提供最流畅的体验，REST API 应该遵循一致的设计准则，以便使它们用起来简单直观。
This document establishes the guidelines Microsoft REST APIs SHOULD follow so RESTful interfaces are developed consistently.
本文档建立了 Microsoft REST APIs 设计指南，用以保证 RESTful 接口开发的一致性。
Developers access most Microsoft Cloud Platform resources via HTTP interfaces.
开发者基本都通过 HTTP 接口访问微软云平台的资源。
Although each service typically provides language-specific frameworks to wrap their APIs, all of their operations eventually boil down to HTTP requests.
尽管每个服务通过特定语言的框架封装了它们的 API，但它们的所有操作最终都归结为 HTTP 请求。
Microsoft must support a wide range of clients and services and cannot rely on rich frameworks being available for every development environment.
微软必须支持多种类型的客户端和服务，且不能依赖于各个开发环境丰富的框架。
Thus a goal of these guidelines is to ensure Microsoft REST APIs can be easily and consistently consumed by any client with basic HTTP support.
因此，这些准则的一个目标是确保任何支持基本 HTTP 协议的客户端都可以简单且一致地使用 Microsoft REST API。
To provide the smoothest possible experience for developers, it's important to have these APIs follow consistent design guidelines, thus making using them easy and intuitive.
为了给开发人员提供最流畅的开发体验，让这些 API 遵循一致的设计准则非常重要，从而使它们用起来简单直观。
This document establishes the guidelines to be followed by Microsoft REST API developers for developing such APIs consistently.
本文档建立了 Microsoft REST API 开发人员应该遵循的指南, 以便统一一致地开发 API。
The benefits of consistency accrue in aggregate as well; consistency allows teams to leverage common code, patterns, documentation and design decisions.
一致性的好处也会累积起来;一致性使团队拥有通用的代码、模式设计、文档风格和设计决策。
These guidelines aim to achieve the following:
-
Define consistent practices and patterns for all API endpoints across Microsoft.
-
Adhere as closely as possible to accepted REST/HTTP best practices in the industry at-large.*
-
Make accessing Microsoft Services via REST interfaces easy for all application developers.
-
Allow service developers to leverage the prior work of other services to implement, test and document REST endpoints defined consistently.
-
Allow for partners (e.g., non-Microsoft entities) to use these guidelines for their own REST endpoint design.
这些准则旨在实现以下目标:
-
为 Microsoft 技术平台中的所有 API 端点定义一致的实现和模式。
-
尽可能地遵循行业普遍接受的 REST/HTTP 最佳实践。
-
使所有程序开发人员都可以简单地通过 REST 接口访问 Microsoft 服务。
-
允许 Service 开发人员利用其他 Service 的工作基础来开发一致的 REST 端点。
-
允许合作伙伴 (如非微软团队) 使用这些准则进行其自己的 REST 端点设计。
*Note: The guidelines are designed to align with building services which comply with the REST architectural style, though they do not address or require building services that follow the REST constraints.
The term "REST" is used throughout this document to mean services that are in the spirit of REST rather than adhering to REST by the book.*
*注：本指南旨在构建符合 REST 架构风格的服务，但不涉及或要求构建遵循 REST 约束的服务。
本文档中使用的“REST”术语代指具有 REST 灵魂的服务，而不是仅仅遵循 REST。
Understanding the philosophy behind the REST Architectural Style is recommended for developing good HTTP-based services.
了解 REST 架构风格背后的一些理念，更有助于开发优秀的基于 HTTP 的服务。
If you are new to RESTful design, here are some good resources:
如果您对 RESTful 设计不熟悉，请参阅以下优秀资源：
[REST on Wikipedia][rest-on-wikipedia] -- Overview of common definitions and core ideas behind REST.
概述 REST 背后的常见定义和核心思想。
[REST Dissertation][fielding] -- The chapter on REST in Roy Fielding's dissertation on Network Architecture, "Architectural Styles and the Design of Network-based Software Architectures"
在 Roy Fielding 关于网络体系结构的论文中"架构风格与基于网络的软件体系结构设计" 一章。
[RFC 7231][rfc-7231] -- Defines the specification for HTTP/1.1 semantics, and is considered the authoritative resource.
HTTP/1.1 语义规范的权威资料。
[REST in Practice][rest-in-practice] -- Book on the fundamentals of REST.
关于 REST 的入门书籍。
These guidelines are applicable to any REST API exposed publicly by Microsoft or any partner service.
Private or internal APIs SHOULD also try to follow these guidelines because internal services tend to eventually be exposed publicly.
这些准则适用于 Microsoft 或其合作伙伴公开发布的服务的所有 REST API。
私人或内部的 API 也大致遵循这些准则, 因为内部服务往往最终会公开。
Consistency is valuable to not only external customers but also internal service consumers, and these guidelines offer best practices useful for any service.
保证一致性不仅对外部客户有利, 而且对内部服务的使用者也很有价值, 这些准则为所有的服务提供了最佳实践。
There are legitimate reasons for exemption from these guidelines.
Obviously a REST service that implements or must interoperate with some externally defined REST API must be compatible with that API and not necessarily these guidelines.
Some services MAY also have special performance needs that require a different format, such as a binary protocol.
当然有许多合理理由可以不遵循这些准则。
显然，实现或必须与某些外部定义的 REST API 互操作的 REST 服务必须与那些 API 兼容，而无法遵循这些准则。
还有一些服务可能由于对性能的特殊的需求，必须使用其他格式，如采用二进制协议。
We do not recommend making a breaking change to a service that pre-dates these guidelines simply for compliance sake.
我们不建议为了遵循这些准则，而过早的对老服务进行重大更改。
The service SHOULD try to become compliant at the next version release when compatibility is being broken anyway.
When a service adds a new API, that API SHOULD be consistent with the other APIs of the same version.
无论如何，当兼容性被破坏时，该服务应该尝试在下一版本中变得合规。
当一个服务添加新的 API 时，该 API 应该与同一版本的其他 API 保持一致。
So if a service was written against version 1.0 of the guidelines, new APIs added incrementally to the service SHOULD also follow version 1.0. The service can then upgrade to align with the latest version of the guidelines at the service's next major release.
因此，如果服务是针对 1.0 版本的指南编写的，那么增量添加到服务的新 API 也应该遵循 1.0 版本指南。然后该服务在下一次主要版本更新时，再去遵循最新版指南。
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
本文档中的"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 和 "OPTIONAL" 等关键字的详细解释见 RFC 2119。
This work is licensed under the Creative Commons Attribution 4.0 International License.
To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
As part of onboarding to Microsoft REST API Guidelines, services MUST comply with the taxonomy defined below.
Microsoft REST API 准则基本要求的一方面就是 服务的分类必须符合以下定义。
Errors, or more specifically Service Errors, are defined as a client passing invalid data to the service and the service correctly rejecting that data.
错误或更具体的服务错误，被定义为客户端将无效数据传递给服务并且服务_明确地_拒绝该数据。
Examples include invalid credentials, incorrect parameters, unknown version IDs, or similar.
例如无效的证书，错误的参数，未知的版本 ID 等。
These are generally "4xx" HTTP error codes and are the result of a client passing incorrect or invalid data.
通常是由于客户端传递错误或无效数据的导致的服务器返回 “4xx” 的 HTTP 错误代码。
Errors do not contribute to overall API availability.
错误不会影响整体 API 的可用性。
Faults, or more specifically Service Faults, are defined as the service failing to correctly return in response to a valid client request.
Faults 或更具体地说服务故障被定义为服务无法正确返回数据以响应有效的客户端请求。
These are generally "5xx" HTTP error codes.
通常会返回 “5xx” HTTP 错误代码。
Faults do contribute to the overall API availability.
故障_会_影响整体 API 的可用性。
Calls that fail due to rate limiting or quota failures MUST NOT count as faults.
由于速率限制或配额不足导致失败的调用绝不能算作故障。
Calls that fail as the result of a service fast-failing requests (often for its own protection) do count as faults.
由于服务 fast-failing 请求而失败的调用（通常是为了保护自己）会被视为错误。
Latency is defined as how long a particular API call takes to complete, measured as closely to the client as possible.
延迟定义为具体 API 被调用完成所需的时长, 尽可能用客户端进行测量。
This metric applies to both synchronous and asynchronous APIs in the same way.
这种测量方法同样适用于同步和异步 API。
For long running calls, the latency is measured on the initial request and measures how long that call (not the overall operation) takes to complete.
对于长时间运行的调用，延迟定义为第一次调用它所需的时长，而非它长时间运行的时长。
Services that expose long operations MUST track "Time to Complete" metrics around those operations.
暴露长时间操作的服务必须跟踪这些操作的 "Time to Complete" 指标。
For a Long Running API, it's possible for both the initial request to begin the operation and the request to retrieve the results to technically work (each passing back a 200), but for the underlying operation to have failed.
对于长时间运行的 API，很可能出现初始请求成功，且后续每次去获取结果时 API 也处于正常运行（每次都回传 200）中，但其底层操作已经失败了的情况。
Long Running faults MUST roll up as Faults into the overall Availability metrics.
长时间运行故障必须作为故障汇总到总体可用性指标中。
To ensure the best possible experience for clients talking to a REST service, clients SHOULD adhere to the following best practices:
为了保证与 REST Service 进行通讯的客户端有最好的体验，客户端应该遵循以下最佳实践：
For loosely coupled clients where the exact shape of the data is not known before the call, if the server returns something the client wasn't expecting, the client MUST safely ignore it.
对于在调用前数据格式不确定的松耦合客户端，如果服务器返回的数据格式错误，客户端必须安全地忽略掉它。
Some services MAY add fields to responses without changing versions numbers.
Services that do so MUST make this clear in their documentation and clients MUST ignore unknown fields.
有的 Service 可能会未更新版本号就在响应中增加字段。
Service 这样做的必须在它的文档中进行明确说明，且客户端必须忽略掉这些未知的字段。
Clients MUST NOT rely on the order in which data appears in JSON service responses.
客户端处理响应数据时一定不能依赖 服务器 JSON 响应数据的顺序。
For example, clients SHOULD be resilient to the reordering of fields within a JSON object.
When supported by the service, clients MAY request that data be returned in a specific order.
例如，当服务器返回的 JSON 对象中的字段顺序变了，客户端也能正确进行解析处理。
当服务端支持时，客户端可以请求有特定顺序的数据。
For example, services MAY support the use of the $orderBy querystring parameter to specify the order of elements within a JSON array.
Services MAY also explicitly specify the ordering of some elements as part of the service contract.
例如，服务器可以支持使用查询参数 orderBy 来使服务器返回有序的 JSON 数组。
服务端也可以在协议中明确指定某些元素按特定方式进行排序。
For example, a service MAY always return a JSON object's "type" information as the first field in an object to simplify response parsing on the client.
例如，服务端可以每次返回 JSON 对象时都把 JSON 对象的类型放在最前面，进而简化客户端解析返回数据的难度。
Clients MAY rely on ordering behavior explicitly identified by the service.
客户端处理数据时可以依赖于服务端明确指定了的排序行为。
Clients requesting OPTIONAL server functionality (such as optional headers) MUST be resilient to the server ignoring that particular functionality.
当客户端请求带可选功能的 Service 时（例如带可选的 header）必须对 Service 有弹性，可以忽略该特定功能。
Humans SHOULD be able to easily read and construct URLs.
URL 应该是易读且格式清晰明了的。
This facilitates discovery and eases adoption on platforms without a well-supported client library.
这有助于简化和推广在没有良好支持的客户端库平台上的使用。
An example of a well-structured URL is:
格式良好的 URL：
https://api.contoso.com/v1.0/people/[email protected]/inbox
An example URL that is not friendly is:
格式不友好的 URL：
https://api.contoso.com/EWS/OData/Users('[email protected]')/Folders('AAMkADdiYzI1MjUzLTk4MjQtNDQ1Yy05YjJkLWNlMzMzYmIzNTY0MwAuAAAAAACzMsPHYH6HQoSwfdpDx-2bAQCXhUk6PC1dS7AERFluCgBfAAABo58UAAA=')
A frequent pattern that comes up is the use of URLs as values.
Services MAY use URLs as values.
For example, the following is acceptable:
一个常见的模式是使用 URL 作为值。
Service 可以使用 URL 作为值。
例如下例：
https://api.contoso.com/v1.0/items?url=https://resources.contoso.com/shoes/fancy
The HTTP 1.1 message format, defined in RFC 7230, in section [3.1.1][rfc-7230-3-1-1], defines no length limit on the Request Line, which includes the target URL.
在 RFC 7230 [3.1.1] [rfc-7230-3-1-1] 章节中定义的 HTTP 1.1 消息格式，定义 Requset（包括其中的目标 URL）没有长度限制。
From the RFC:
HTTP does not place a predefined limit on the length of a
request-line. [...] A server that receives a request-target longer than any URI it wishes to parse MUST respond
with a 414 (URI Too Long) status code.
Services that can generate URLs longer than 2,083 characters MUST make accommodations for the clients they wish to support.
当 Service 生成的 URL 长度超过 2083 个字符时必须考虑如何兼容将支持的客户端。
Here are some sources for determining what target clients support:
不同客户端支持的最长 URL 长度参见以下资料：
Also note that some technology stacks have hard and adjustable url limits, so keep this in mind as you design your services.
另请注意，某些技术栈具有难以调整的 url 限制，因此请在设计 service 时牢记这点。
In addition to friendly URLs, resources that can be moved or be renamed SHOULD expose a URL that contains a unique stable identifier.
除了友好的 URL 之外，可以移动或重命名的资源也应该暴露一个包含唯一固定标识符的 URL。
It MAY be necessary to interact with the service to obtain a stable URL from the friendly name for the resource, as in the case of the "/my" shortcut used by some services.
在与 Service 进行交互时可能需要通过友好的名称来获取资源固定的 URL，例如某些 Service 使用的“/my”快捷方式。
The stable identifier is not required to be a GUID.
固定标识符不一定必需得是 GUID。
An example of a URL containing a canonical identifier is:
包含规范标识符的 URL 示例：
https://api.contoso.com/v1.0/people/7011042402/inbox
Operations MUST use the proper HTTP methods whenever possible, and operation idempotency MUST be respected.
HTTP methods are frequently referred to as the HTTP verbs.
操作必须尽可能使用正确的 HTTP 方法，且必须遵守操作幂等。
HTTP 方法又通常被称为 HTTP 动词。
The terms are synonymous in this context, however the HTTP specification uses the term method.
这些术语在这种情况下是同义词，但 HTTP 规范了使用术语的方法。
Below is a list of methods that Microsoft REST services SHOULD support.
下面是 Microsoft REST Service 应该支持的方法列表。
Not all resources will support all methods, but all resources using the methods below MUST conform to their usage.
并非所有资源都支持所有方法，但使用下面方法的所有资源必须遵从下面的用法。
| Method 方法 | Description 描述 | Is Idempotent 是否幂等 |
|---|---|---|
| GET | Return the current value of an object 返回对象的当前值 |
True |
| PUT | Replace an object, or create a named object, when applicable 替换对象，或在适用时创建一个命名对象 |
True |
| DELETE | Delete an object 删除对象 |
True |
| POST | Create a new object based on the data provided, or submit a command 根据提供的数据创建一个新对象，或提交一个命令 |
False |
| HEAD | Return metadata of an object for a GET response. Resources that support the GET method MAY support the HEAD method as well 为 GET 响应返回对象的元数据。支持 GET 方法的资源也可以支持 HEAD 方法 |
True |
| PATCH | Apply a partial update to an object 对对象应用部分更新 |
False |
| OPTIONS | Get information about a request; see below for details. 获取有关 Request 的信息；详见下文。 |
True |
Table 1
POST operations SHOULD support the Location response header to specify the location of any created resource that was not explicitly named, via the Location header.
POST 操作应该支持 Location 响应 header，通过 Location 响应 header 指定任何未明确命名的已创建资源的位置。
As an example, imagine a service that allows creation of hosted servers, which will be named by the service:
例如，一个 service 允许创建并命名托管服务器：
POST http://api.contoso.com/account1/serversThe response would be something like:
响应将会是这个样子：
201 Created
Location: http://api.contoso.com/account1/servers/server321Where "server321" is the service-allocated server name.
“server321” 是 service 创建的托管服务器的名称。
Services MAY also return the full metadata for the created item in the response.
Services 也可以在响应中返回创建项的完整元数据。
PATCH has been standardized by IETF as the method to be used for updating an existing object incrementally (see [RFC 5789][rfc-5789]).
PATCH 已经被 IETF 标准化为递进式更新现有对象的方法(参考 [RFC 5789][rfc-5789])。
Microsoft REST API Guidelines compliant APIs SHOULD support PATCH.
符合 Microsoft REST API 指南的 API 应该支持 PATCH 方法。
Services that allow callers to specify key values on create SHOULD support UPSERT semantics, and those that do MUST support creating resources using PATCH.
允许调用者在创建资源时指定 key 的 service 应该支持 UPSERT 语义，可以这样做的 service 也必须支持通过 PATCH 创建资源。
Because PUT is defined as a complete replacement of the content, it is dangerous for clients to use PUT to modify data.
因为 PUT 被定义为完全替换原数据，所以客户端直接使用 PUT 修改数据很危险。
Clients that do not understand (and hence ignore) properties on a resource are not likely to provide them on a PUT when trying to update a resource, hence such properties could be inadvertently removed.
当对资源属性不了解的客户端试图通过 PUT 更新数据时，由于对属性不了解，很可能忽略了某些属性，进而导致这些属性被无意删除。
Services MAY optionally support PUT to update existing resources, but if they do they MUST use replacement semantics (that is, after the PUT, the resource's properties MUST match what was provided in the request, including deleting any server properties that were not provided).
Service 可以支持 PUT 更新现有资源，但必须使用替换语义（也就是说，在 PUT 后，资源的所有属性必须与请求中提供的内容相匹配，包括删除所有未提供的服务端属性）。
Under UPSERT semantics, a PATCH call to a nonexistent resource is handled by the server as a "create," and a PATCH call to an existing resource is handled as an "update." To ensure that an update request is not treated as a create or vice-versa, the client MAY specify precondition HTTP headers in the request.
在 UPSERT 语义下，对不存在资源 PATCH 调用时服务器作为“create”来处理，对现有资源 PATCH 调用时服务器作为“update”来处理。为了确保 update 请求不被视为 create（反之亦然），客户端可以在请求中指定预先配置的 HTTP headers。
The service MUST NOT treat a PATCH request as an insert if it contains an If-Match header and MUST NOT treat a PATCH request as an update if it contains an If-None-Match header with a value of "*".
如果一个 PATCH 请求包含一个 If-Match header，那么 service 绝不能把这个 PATCH 请求当做 insert，并且如果它包含一个值为“*”的 If-None-Match header，则不能将该 PATCH 请求当做 update。
If a service does not support UPSERT, then a PATCH call against a resource that does not exist MUST result in an HTTP "409 Conflict" error.
如果 service 不支持 UPSERT，那么对不存在资源的 PATCH 调用必须导致 HTTP "409 Conflict" 错误。
OPTIONS allows a client to retrieve information about a resource, at a minimum by returning the Allow header denoting the valid methods for this resource.
OPTIONS 允许客户端检索有关资源的信息，至少可以返回表示该资源的有效方法的 Allow header。
In addition, services SHOULD include a Link header (see [RFC 5988][rfc-5988]) to point to documentation for the resource in question:
此外, service 应该包括 Link header (参考 [RFC 5988][rfc-5988]) 以指向有关的文档资源：
Link: <{help}>; rel="help"Where {help} is the URL to a documentation resource.
其中 {help} 是文档资源的 URL.
For examples on use of OPTIONS, see [preflighting CORS cross-domain calls][cors-preflight].
有关使用 OPTIONS 的示例，请参考 [preflighting CORS cross-domain calls][cors-preflight]。