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

前面我们说了，如果API的设计更规范更合理，在很大程度上能够提高联调的效率，降低沟通成本。那么什么是好的API设计？这里我们不得不提到REST API。

关于REST API的书籍很多，但是完整完善实践丰富的设计指导并不多见，我们有幸看到了微软团队的作品——Microsoft REST API Guidelines，因此才有了此篇内容。由于公众号文章内容字数有限，因此我们将翻译稿拆分并分享出来，并且给出英文对照。翻译的不对之处，请多多指教。

另外，由于本周聚焦在架构层面，下周我们争取录制更多教程并分享出来。

 

5 Taxonomy 分类

 

As part of onboarding to Microsoft REST API Guidelines, services MUST comply with the taxonomy defined below.

Microsoft REST API 准则基本要求的一方面就是 服务的分类必须符合以下定义。

 

5.1 Errors 错误

Errors, or more specifically Service Errors, are defined as a client passing invalid data to the service and the servicecorrectly 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 的可用性。

 

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

 

5.2 Faults  故障

Faults, or more specifically Service Faults, are defined as the service failing to correctly return in response to a valid client request.

故障， 或更具体地说服务故障被定义为服务无法正确返回数据以响应有效的客户端请求。

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 请求而失败的调用（通常是为了保护自己）会被视为故障。

 

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

fast-failing   快速失败

safe-failing 安全失败

 

 

5.3 Latency 延迟

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.

对于长时间运行的调用，延迟定义为第一次调用它所需的时长，而非它长时间运行的时长。

 

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

 

5.4 Time to complete 完成时间

Services that expose long operations MUST track "Time to Complete" metrics around those operations.

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

 

5.5 Long running API faults 长时间运行的API故障

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.

长时间运行故障必须作为故障汇总到总体可用性指标中。