> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/zh/docs/versioning

# 版本控制与弃用

API 版本是路径的一部分，例如 `/v1/status`。在同一版本内，现有请求会继续正常工作。本页说明哪些内容可能发生变化、你会获得多长的通知期，以及如何找出需要更新的请求。

### 无需通知的变更

新的端点、可选参数、响应字段、现有选项列表中的新值、响应头和错误码可能随时添加。请让客户端忽略不认识的字段，并妥善处理新增的值。

### 破坏性变更

删除或重命名端点、参数或字段，或更改其含义，只会在至少提前 12 个月通知之后进行。在此期间，旧形式仍可继续使用，使用旧形式的请求的响应会带有 `Deprecation` 和 `Sunset` 请求头，并且该变更会列在更新日志中。

### 响应键命名

大多数响应键为 snake_case。若要让所有键都以 snake_case 返回，请添加 `naming=snake` 或发送 `DomScan-Naming: snake` 请求头。这是可选启用的功能，因此默认响应不会改变。参见[snake_case 键](https://domscan.net/zh/docs/response-format#naming)。

### 已弃用的别名

以下旧参数目前仍可使用。每个参数至少会保持可用到其停用日期。请在此之前迁移到替代参数。

| 参数 | 端点 | 请改用 | 弃用日期 | 停用日期 |
| --- | --- | --- | --- | --- |
| `prefer_cache` | `GET /v1/status` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/status` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `cache_skip` | `GET /v1/status` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `cache-skip` | `GET /v1/status` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `options.prefer_cache` (JSON 请求体) | `POST /v1/status/bulk` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `prefer_cache` (JSON 请求体) | `POST /v1/status/bulk` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `options.skip_cache` (JSON 请求体) | `POST /v1/status/bulk` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `options.cache_skip` (JSON 请求体) | `POST /v1/status/bulk` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `options.cache-skip` (JSON 请求体) | `POST /v1/status/bulk` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `prefer_cache` | `GET /v1/subdomains` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/tech` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/categorize` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/identity-assets` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/identity-resolution` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/url-intelligence` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/agent-readiness` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/robots` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `refresh` | `GET /v1/ssl/deep-scan` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `cursor` (数值) | `GET /v1/certificates` | `cursor=<next_cursor>` | 2026-10-10 | 2027-10-10 |
| `offset` | `GET /v1/email/blacklist` | `cursor=<next_cursor>` | 2026-10-10 | 2027-10-10 |

### 检测弃用

使用已弃用别名的请求会收到以下响应头。响应体保持不变。

- `Deprecation`: 别名被弃用的日期，格式为 `@` 后跟 Unix 秒数 (RFC 9745)。

- `Sunset`: 别名最早可能停止工作的日期 (RFC 8594)。

- `Link`: 指向本页的链接，带有 `rel="deprecation"`。

```bash
curl -i -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/status?name=example&tlds=com&skip_cache=true"

Deprecation: @1791590400
Sunset: Sun, 10 Oct 2027 00:00:00 GMT
Link: <https://domscan.net/docs/versioning#deprecated-aliases>; rel="deprecation"; type="text/html"
```

浏览器可以读取这三个请求头。请记录日志或针对 `Deprecation` 设置告警，以便在停用日期之前找出需要更新的代码。

每一项弃用也会在[API 更新日志](https://domscan.net/zh/changelog)中公布。