> 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/ja/docs/versioning

# バージョニングと非推奨

API のバージョンはパスに含まれます。 たとえば /v1/status です。 同じバージョンの中では、既存のリクエストは引き続き動作します。

API のバージョンはパスに含まれます。たとえば `/v1/status` です。同じバージョンの中では、既存のリクエストは引き続き動作します。このページでは、何が変更される可能性があるか、どの程度前に通知されるか、更新が必要なリクエストをどのように見つけるかを説明します。

### 通知なしで行われる変更

新しいエンドポイント、任意パラメータ、レスポンスフィールド、既存の選択肢リストへの値の追加、レスポンスヘッダー、エラーコードは、いつでも追加される可能性があります。クライアントは、未知のフィールドを無視し、新しい値を適切に処理するように実装してください。

### 破壊的変更

エンドポイント、パラメータ、フィールドの削除や名前変更、またはその意味の変更は、少なくとも12か月前の告知を行った後にのみ実施されます。その期間中、旧形式は引き続き動作し、旧形式を使用したリクエストへのレスポンスには `Deprecation` ヘッダーと `Sunset` ヘッダーが付与され、変更内容は変更履歴に掲載されます。

### レスポンスキーの命名

レスポンスキーのほとんどは snake_case です。すべてのキーを snake_case で受け取るには、`naming=snake` を追加するか、`DomScan-Naming: snake` ヘッダーを送信してください。これはオプトイン方式のため、デフォルトのレスポンスは変わりません。[snake_case キー](https://domscan.net/ja/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"
```

ブラウザーは3つのヘッダーすべてを読み取れます。`Deprecation` をログに記録するかアラートを設定して、廃止日までに更新が必要なコードを見つけてください。

非推奨はすべて[API 変更履歴](https://domscan.net/ja/changelog)でも告知されます。