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.

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