REST API设计指导——译自Microsoft REST API Guidelines（二）

由于文章内容较长，只能拆开发布。翻译的不对之处，请多多指教。

另外：最近团队在做一些技术何架构的研究，视频教程只能争取周末多录制一点，同时预计在下周我们会展开一次直播活动，内容围绕容器技术这块。

所有章节我们翻译校对完成后，将会将最终定稿签入到我们的Github开源库托管，方便大家查阅和校正。同时，我们推荐将此规范作为团队的REST API设计指导和规范。

上篇内容：

REST API设计指导——译自Microsoft REST API Guidelines（一）

 

3 Introduction 介绍

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 API 节点。

• 允许合作伙伴 (如非微软团队) 使用这些准则来设计自己的 REST API。

 

*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”术语代指具有 RESTful风格的服务，而不是仅仅遵循 REST。

 

3.1 Recommended reading 推荐阅读

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:

• [REST on Wikipedia][rest-on-wikipedia] -- Overview of common definitions and core ideas behind 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"

• [RFC 7231][rfc-7231] -- Defines the specification for HTTP/1.1 semantics, and is considered the authoritative resource.

• [REST in Practice][rest-in-practice] -- Book on the fundamentals of REST.

 

如果您对 RESTful 设计不熟悉，请参阅以下优秀资源：

• 概述 REST 背后的常见定义和核心思想。

• 在 Roy Fielding 关于网络体系结构的论文中"架构风格与基于网络的软件体系结构设计" 一章。

• HTTP/1.1 语义规范的权威资料。

• 关于 REST 的入门书籍。

 

译者注：上一篇说了，REST 指的是一组架构约束条件和原则。那么满足这些约束条件和原则的应用程序或设计就是 RESTful。

 

4 Interpreting the guidelines 解读指导 

4.1 Application of the guidelines 应用指导

These guidelines are applicable to any REST API exposed publicly by Microsoft or any partner service.

这些准则适用于 Microsoft 或其合作伙伴公开发布的所有 REST API 服务。

 

Private or internal APIs SHOULD also try to follow these guidelines because internal services tend to eventually be exposed publicly.

私人或内部的 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.

显然，实现或必须与某些外部定义的 REST API 互操作的 REST 服务必须与那些 API 兼容，而无法遵循这些准则。

 

Some services MAY also have special performance needs that require a different format, such as a binary protocol.

还有一些服务可能由于对性能的特殊的需求，必须使用其他格式，如采用二进制协议。

 

4.2 Guidelines for existing services and versioning of services 

现有服务和服务版本指南

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 版本指南。然后该服务在下一次主要版本更新时，再去遵循最新版指南。

4.3 Requirements language 要求的语言

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。

 

4.4 License 许可证

This work is licensed under the Creative Commons Attribution 4.0 International License. 
本文的产权使用Creative Commons Attribution 4.0 International License。 

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

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. 

要查看此许可证的副本，请访问http://creativecommons.org/licenses/by/4.0/

或向Creative Commons发送一封信，PO Box 1866，Mountain View，CA 94042，USA。