バージョニングと廃止ポリシー
このページは、atouch API が何を予告なく変えるか / 何を予告して変えるかを定めます。 連携を長く動かし続けるために、実装前に一読してください。
バージョンの表し方
メジャーバージョンは URL パスに含めます（現行は /v1）。
| 変更の種類 | 扱い | 例 |
|---|---|---|
| 後方互換な追加 | 予告なく現行バージョンに入ります | 新しいエンドポイント / 応答への新フィールド追加 / enum への値追加 / 新しいエラーコード |
| 後方互換でない変更 | 新しいメジャーバージョン（/v2）として提供します | フィールドの削除・改名、型の変更、既定の挙動の変更 |
メジャーバージョンを上げる場合、旧バージョンは最低 6 か月並行して稼働させます。
現行バージョンに入った変更は、変更履歴に載せます。
クライアント実装のお願い（重要）
後方互換な追加を「予告なく入れる」ため、次を守った実装にしてください。守られていないと、 本来は無害な追加でクライアント側が壊れます。
- 知らないフィールドは無視する。 応答に見覚えのないキーが増えても失敗しないこと。
- 知らない enum 値を受け入れる。
statusなどの値は将来増えます。値を厳密に検証して 例外を投げる実装（多くのコード生成 SDK の既定）は、値が 1 つ増えただけで動かなくなります。 受け取った値をそのまま保持し、未知の値は「その他」として扱ってください。 - 知らないエラーコードに備える。 分岐は HTTP ステータスを主、
error.codeを従にしてください。 - 配列の順序に依存しない。 明示的に順序を定めている応答以外、順序は保証しません。
- キーが省略されることに備える。 一部の項目（注文明細の
variant、商品のreserved_inventory）は、取得できなかったときに キーごと省略します。キーが無いことをnullや0と同じに扱わないでください（意味が違います）。
廃止（deprecation）の進め方
エンドポイントやフィールドを廃止する場合、次の順で進めます。
告知の手段
| 手段 | 内容 |
|---|---|
| 登録メールアドレス | クライアント登録時のアドレス宛にお知らせします |
| 開発者コンソールのお知らせ | ログイン後の画面上部に表示します |
Deprecation レスポンスヘッダ | 廃止予定の経路への応答に付きます（RFC 9745） |
Sunset レスポンスヘッダ | 提供終了の日時を示します（RFC 8594） |
猶予期間
予告から提供終了まで、最低 6 か月を置きます。メジャーバージョン全体（/v1 → /v2）でも、個別のエンドポイント・フィールドでも同じです。
| 対象 | 予告から提供終了までの最低期間 |
|---|---|
メジャーバージョン全体（/v1 → /v2） | 6 か月 |
| 個別のエンドポイント / フィールド | 6 か月 |
セキュリティ上の緊急対応が必要な場合はこの限りではありません。その場合も、判明した時点で即時に告知します。
現在の状態
/v1 を提供しています。廃止予定のエンドポイント・フィールドはありません。