バージョニングの考え方

QA ZERO API は 2層 バージョニングを使います。この違いが分かっていると「クライアントが数年安定する」か「四半期ごとに壊れる」かの分かれ目になります。

2つの層

層	フォーマット	変わる条件	どこに現れるか
version	YYYY-MM-DD	API の形に対する破壊的変更のみ	URL (?version=2025-10-20)
update	YYYY-MM-DD	同一バージョン内の非破壊追加	/guide レスポンスの api_update、プラグインの QAHM_API_UPDATE

• version は 安定した契約 です。クライアントに pin するのはこれ。破壊的変更はまれで、事前に予告され、24ヶ月間並行サポートされます。
• update は 機能時計 です。非破壊追加 (新マテリアル、新カラム、新機能) は version を触らずに update を bump するので、新機能を必要としないクライアントは動き続けます。

クライアントの読み方

典型的な AI クライアントの起動時:

1. /guide?version=2025-10-20 を呼ぶ。
2. レスポンスの api_update を記録。
3. features_detail マップ (エントリごとの since タグ付き) を記録。
4. 機能を使う前に、その機能の since を自分の知っている api_update と比較する。since > api_update なら、サーバーはまだサポートしていない可能性があるので、優雅にフォールバックする — クラッシュしない。

これは Stripe / AWS モデルを AI クライアント向けに調整したものです。私たちは誰も壊さずに改善を頻繁に出荷でき、クライアントは実行時に新しい機能を検出できます。

since タグ

qal-validation.yaml の各機能エントリと、(オプションで) materials.yaml の各マテリアル・各フィールドは since: YYYY-MM-DD タグを持てます。ルール:

• since 無し: このバージョン導入時から存在する。常に使える。
• since 有り: その update 日付で追加された。サーバーの api_update >= since のときだけ使える。

タグの粒度がクエリ単位ではなく機能単位なのは、これが AI クライアントが組み立て時に 「これを使っていいのか?」 を判定できる唯一の方法だからです。これより粗い粒度だと失敗時リトライが発生しますが、リトライはまさに私たちが無くそうとしているものです。

破壊的変更とは?

version を bump する変更:

• マテリアル、カラム、トップレベルキーの削除やリネーム。
• 既存のデシリアライザを壊す形でのカラム型変更。
• クエリの必須フィールド集合の変更。
• エラーレスポンスの形の変更。

update だけを bump する変更:

• 新マテリアルの追加。
• 既存マテリアルへの新カラム追加。
• 新機能の追加 (since タグ付き)。
• 新しいオプショナルリクエストフィールドの追加。
• calc で使える関数のホワイトリスト拡張。
• 公開契約を変えない実装の詳細変更。

ある変更が破壊的かどうか迷ったら破壊的とみなし、version を bump してください。黙って壊すのは、この仕組みが存在理由にしている「防ぎたいミス」そのものです。

次に読むページ

• Changelog — バージョン 2025-10-20 の Update Ledger。各 update 日付と追加内容。
• 互換性ガイド — バージョンサポート期間と移行ポリシー。