<commit_before># HTTP API 设计指南
> 翻译自 `HTTP API Design Guide` [https://github.com/interagent/http-api-design](https://github.com/interagent/http-api-design)

## 前言

这篇指南介绍了大量的 HTTP+JSON 的api设计风格，最初摘录自heroku平台的api设计指引 [Heroku 平台 API 指引](https://devcenter.heroku.com/articles/platform-api-reference)。

这篇指南除了介绍那些API，同时也适用于heroku平台新集成的API,我们希望那些在Heroku之外的API设计者也感兴趣。

我们的目标是一致性，专注业务逻辑同时避免设计上的空想。我们一直在寻找一种良好的、统一的、显而易见的API设计方式，未必只有一种方式。

我们假设你熟悉基本的 HTTP+JSON API 设计方式，但是，不一定包含在此篇指南里面的所有内容。

我们欢迎你为这篇指南做[贡献](https://github.com/interagent/http-api-design/blob/master/CONTRIBUTING.md)。

## 目录

* 基础
  * 要求 TLS
  * 指定可接受头信息的版本
  * 支持Etag缓存
  * 使用请求ID（Request-Ids）追踪请求
  * 按范围分页
* 请求（Requests）
  * 返回合适的状态码
  * 提供全部可用的资源
  * 在请求的body体使用JSON格式数据
  * 使用统一的资源路径格式
  * 路径和属性要小写
  * 支持方便的无id间接引用
  * 最小化路径嵌套
* 响应（Responses）
  * 提供资源的(UU)ID
  * 提供标准的时间戳
  * 使用UTC（世界标准时间）时间，用ISO8601进行格式化
  * 嵌套外键关系
  * 生成结构化的错误
  * 显示频率限制状态
  * 保证响应JSON最小化
* 工件（Artifacts）
  * 提供机器可读的JSON模式
  * 提供人类可读的文档
  * 提供可执行的例子
  * 描述稳定性
* 译者注


### 基础

#### 要求 TLS

访问 API 要求 TLS, 没有例外。 不值得去解析什么时间需要 TLS 什么时候不需要，任何访问都要求 TLS。

理想情况下，拒绝任何非 TLS 请求，不响应基于 http 或是80端口的请求去避免任何不安全的数据交换。环境中不响应的情况返回状态`403 Forbidden`。

重定向是不推荐的，因为他们允许不好的客户端的行为，不提供任何明确的目标。客户依赖重定会加倍服务器流量和渲染 TLS 也没有作用，因为敏感数据已经无用在第一次调用已经暴露。
 
#### 指定可接受头信息的版本

在开始的时候指定API版本，通过`Accepts`与自定义内容类型头(content type)同时传递版本, 例如:

```
Accept: application/vnd.heroku+json; version=3
```

最好不要给出一个默认的版本, 而是要求客户端明确指明他们要使用特定的版本。

#### 支持Etag缓存

在所有请求响应中包含一个`ETag`头，标识出返回资源的版本。这样就允许用户去缓存这些资源，请求时将`ETag`的值设置到`If-None-Match`头信息中就可以知道是否需要更新缓存了。

#### 使用请求ID（Request-Ids）追踪请求

为每一个请求响应包含一个`Request-Id`字段，使用UUID生成该ID。如果服务器和客户端同时记录下这些内容，这样对于跟踪和调试请求非常有帮助。

#### 按范围分页

对于服务器响应的大量数据我们应该为此分页。
使用`Content-Range` 头传递分页请求。这里有个例子详细的说明了请求和响应头、状态码，限制条件、排序以及分页处理：[Heroku Platform API on Ranges](https://devcenter.heroku.com/articles/platform-api-reference#ranges).


###请求（Requests）

#### 返回合适的状态码

为每一次的响应返回合适的HTTP状态码. 好的响应应该使用如下的状态码:

* `200`: `GET`请求成功, 及`DELETE`或`PATCH`同步请求完成，或者`PUT`同步更新一个已存在的资源
* `201`: `POST` 同步请求完成，或者`PUT`同步创建一个新的资源
* `202`: `POST`, `PUT`, `DELETE`, 或 `PATCH` 请求接收，将被异步处理
* `206`: `GET` 请求成功, 但是只返回一部分，参考：[上文中范围分页](#按范围分页)

使用身份认证（authentication）和授权（authorization）错误码时需要注意：

* `401 Unauthorized`: 用户未认证，请求失败
* `403 Forbidden`: 用户无权限访问该资源，请求失败

当用户请求错误时，提供合适的状态码可以提供额外的信息：

* `422 Unprocessable Entity`: 请求被服务器正确解析，但是包含无效字段
* `429 Too Many Requests`: 因为访问频繁，你已经被限制访问，稍后重试
* `500 Internal Server Error`: 服务器错误，确认状态并报告问题<commit_msg>update to cleanup/tweaks around versioning<commit_after># HTTP API 设计指南
> 翻译自 `HTTP API Design Guide` [https://github.com/interagent/http-api-design](https://github.com/interagent/http-api-design)

## 前言

这篇指南介绍了大量的 HTTP+JSON 的api设计风格，最初摘录自heroku平台的api设计指引 [Heroku 平台 API 指引](https://devcenter.heroku.com/articles/platform-api-reference)。

这篇指南除了介绍那些API，同时也适用于heroku平台新集成的API,我们希望那些在Heroku之外的API设计者也感兴趣。

我们的目标是一致性，专注业务逻辑同时避免设计上的空想。我们一直在寻找一种良好的、统一的、显而易见的API设计方式，未必只有一种方式。

我们假设你熟悉基本的 HTTP+JSON API 设计方式，但是，不一定包含在此篇指南里面的所有内容。

我们欢迎你为这篇指南做[贡献](https://github.com/interagent/http-api-design/blob/master/CONTRIBUTING.md)。

## 目录

* 基础
  * 要求 TLS
  * 要求接收头信息中指定版本号
  * 支持Etag缓存
  * 为内省而提供 Request-Id
  * 按范围分页
* 请求（Requests）
  * 返回合适的状态码
  * 提供全部可用的资源
  * 在请求的body体使用JSON格式数据
  * 使用统一的资源路径格式
  * 路径和属性要小写
  * 支持方便的无id间接引用
  * 最小化路径嵌套
* 响应（Responses）
  * 提供资源的(UU)ID
  * 提供标准的时间戳
  * 使用UTC（世界标准时间）时间，用ISO8601进行格式化
  * 嵌套外键关系
  * 生成结构化的错误
  * 显示频率限制状态
  * 保证响应JSON最小化
* 工件（Artifacts）
  * 提供机器可读的JSON模式
  * 提供人类可读的文档
  * 提供可执行的例子
  * 描述稳定性
* 译者注


### 基础

#### 要求安全连接（Secure Connections）

所有的访问API行为，都需要用 TLS 通过安全连接来访问。不值得去解释什么时间需要 TLS 什么时候不需要 TLS，直接规定任何访问都要求 TLS。

理想情况下，拒绝任何非 TLS 请求，不响应基于 http 或是80端口的请求去避免任何不安全的数据交换。环境中不响应的情况返回状态`403 Forbidden`。

重定向是不推荐的，因为他们允许不好的客户端的行为，不提供任何明确的目标。客户依赖重定会加倍服务器流量和渲染 TLS 也没有作用，因为敏感数据已经无用在第一次调用已经暴露。
 
#### 要求接收头信息中指定版本号

版本和版本之间的过渡对于设计和操作API是一个非常大的挑战。这样，最好是开始时就有一些机制来缓和这个过渡。

为了防止意外,打破更改用户，最好是与所有请求都需要指定一个版本。为了将来的修改，最好不要提供默认的版本。

最好是在头信息中指定版本号，和其它数据一起，通过`Accepts`自定义内容类型(content type)同时传递，例如:

```
Accept: application/vnd.heroku+json; version=3
```

#### 支持Etag缓存

在所有请求响应中包含一个`ETag`头，标识出返回资源的版本。这样就允许用户去缓存这些资源，请求时将`ETag`的值设置到`If-None-Match`头信息中就可以知道是否需要更新缓存了。

#### 为内省而提供 Request-Id

为每一个请求响应包含一个`Request-Id`字段，使用UUID作为该值。如果服务器和客户端同时记录下这些内容，这样对于跟踪和调试请求非常有帮助。

为每一个请求响应包含一个`Request-Id`字段，并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值，它能主我们提供一种机制来跟踪、诊断和调试请求。

#### 按范围分页

对于服务器响应的大量数据我们应该为此分页。
使用`Content-Range` 头传递分页请求。这里有个例子详细的说明了请求和响应头、状态码，限制条件、排序以及分页处理：[Heroku Platform API on Ranges](https://devcenter.heroku.com/articles/platform-api-reference#ranges).


###请求（Requests）

#### 返回合适的状态码

为每一次的响应返回合适的HTTP状态码. 好的响应应该使用如下的状态码:

* `200`: `GET`请求成功, 及`DELETE`或`PATCH`同步请求完成，或者`PUT`同步更新一个已存在的资源
* `201`: `POST` 同步请求完成，或者`PUT`同步创建一个新的资源
* `202`: `POST`, `PUT`, `DELETE`, 或 `PATCH` 请求接收，将被异步处理
* `206`: `GET` 请求成功, 但是只返回一部分，参考：[上文中范围分页](#按范围分页)

使用身份认证（authentication）和授权（authorization）错误码时需要注意：

* `401 Unauthorized`: 用户未认证，请求失败
* `403 Forbidden`: 用户无权限访问该资源，请求失败

当用户请求错误时，提供合适的状态码可以提供额外的信息：

* `422 Unprocessable Entity`: 请求被服务器正确解析，但是包含无效字段
* `429 Too Many Requests`: 因为访问频繁，你已经被限制访问，稍后重试
* `500 Internal Server Error`: 服务器错误，确认状态并报告问题
{'fraction_non_alphanumeric': 0.12900058904378559, 'fraction_numerical': 0.014529746711172197, 'mean_word_length': 6.873261205564142, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2030217', 'n_tokens_mistral': 3704, 'n_tokens_neox': 4167, 'n_words': 283}