REST API設計指導——譯自Microsoft REST API Guidelines（二）
由於文章內容較長，只能拆開發布。翻譯的不對之處，請多多指教。
另外：最近團隊在做一些技術何架構的研究，視訊教程只能爭取週末多錄製一點，同時預計在下週我們會展開一次直播活動，內容圍繞容器技術這塊。
所有章節我們翻譯校對完成後，將會將最終定稿簽入到我們的Github開源庫託管，方便大家查閱和校正。同時，我們推薦將此規範作為團隊的REST API設計指導和規範。
上篇內容：
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。