APIバージョン：互換性を確認して移行する

公開 07/05/2026 · 更新 23/10/2026 · APIと連携サービス · 6 分で読めます · 執筆 Cyber Intelligence Embassy

要点

番号を変えるだけでは利用側を保護できません。互換性には、メッセージと実際のクライアントが依存する振る舞いの両方が含まれます。

この記事の内容

クライアントの視点で評価する

表はレビューの手掛かりであり、普遍的な保証ではありません。項目の追加で厳格な読み取り処理が失敗し、列挙値の追加で網羅的な分岐が壊れる場合もあります。利用者、ライブラリ、前提を把握します。

変更	確認するリスク	必要な証拠
項目の削除や改名	読み取り不能	明示的な移行とクライアント試験。
任意項目の追加	厳格な読み取りや名前衝突	既存利用側での試験。
応答の列挙値追加	分岐の網羅漏れ	未知の値への対処。
既定値の変更	業務結果の変化	値を明示しない事例の比較。

併存を計画する

新旧の構造、既定値、エラー、ページ分割、権限を説明し、代表的な利用側の事例で契約テストを行います。
版の選択方法を明示します。サービスの版とOpenAPI文書の版を区別し、キャッシュやゲートウェイも確認します。
日程、移行手順、連絡先を公開します。利用状況を必要な範囲で測り、データと整合する切り戻しを準備します。

非推奨と停止を区別する

Deprecationは非推奨の資源を示し、Sunsetは利用不能となる予定時期を示せます。ヘッダー自体はクライアントを移行しません。残る利用者、義務、復旧手順を確認してから版を停止します。

一次資料

消費者への影響を考慮したバージョン管理

URLに番号を追加しても、既存のクライアントは維持されません。パスが同じでも、型、期待値、動作、またはエラー応答が変更されると、互換性が失われる可能性があります。

アクティブなクライアントと使用状況を調査する。
古いクライアントバージョンを新しい契約と照合してテストする。
共存期間を設定し、廃止前に使用状況を調査する。

一次資料：IETF RFC 9457 — Problem Details for HTTP APIs. 関連する方法：実践ガイドを読む.

非同期APIジョブ

要求の受理は処理の完了を証明しません。

アカウント、操作、再利用する識別子
状態、時刻、照会間隔、有効期限
成果、エラー、取消、残る影響
許可された単一のジョブと中断後の確認済み結果

再現できる受け入れ事例

架空の例です。顧客や実際の観測結果を示すデータではありません。

事例の入力を見る

{
    "job_id": "J-42",
    "timeline": [
        {
            "elapsed_seconds": 0,
            "http": 202,
            "state": "pending"
        },
        {
            "elapsed_seconds": 5,
            "http": 200,
            "state": "running"
        },
        {
            "elapsed_seconds": 6,
            "http": 200,
            "state": "cancel_requested"
        },
        {
            "elapsed_seconds": 7,
            "http": 200,
            "state": "succeeded"
        }
    ]
}

期待される判断

状態取得の 200 は処理完了を意味しません。キャンセル要求後も、確認済みの最終結果に基づいて判断します。

キャンセル要求が間に合わない場合

架空の例：同じジョブ J-42 を送信後の秒数で追跡します。状態名はこの例の契約で定めたもので、HTTP が規定する名前ではありません。

時点	応答と状態	確認できること
+0 s	HTTP 202 · pending	処理を受け付けた段階で、最終結果は未確認です。
+5 s	HTTP 200 · running	状態の取得には成功しましたが、処理は継続中です。
+6 s	HTTP 200 · cancel_requested	停止要求は記録されましたが、キャンセルは未確定です。
+7 s	HTTP 200 · succeeded	処理完了が先行しました。確認済みの成功を表示し、影響を確認します。キャンセル済みとは表示しません。

Microsoft — Asynchronous request-reply

202は将来の完了を証明する？

しない。処理の受理を示し、最終結果は示さない。操作の状態を確認する。

一次資料：MDN — 202 Accepted. 関連する方法：実践ガイドを読む.

ソフトウェア更新：署名者の変更を検証する

署名付き成果物が承認された提供者、ビルド工程、版に対応しているか判断します。

新しいパッケージを調べる前に許可する提供者、鍵または証明書の識別情報、発行者、ビルド工程を記録します。ソフトウェアと既に信頼する確認経路に結び付けます。成果物だけに自身の受入方針を定めさせません。
受信したファイルのダイジェストと証明の対象を照合します。予定した信頼の起点で署名を検証し、識別情報、ビルダー、パラメーターを確認します。別の識別情報による暗号学的に有効な署名はサービスの方針を満たしません。
予告された更新、想定外の発行者、署名欠落、別ファイルを試します。新しい識別情報が未確認なら成果物を保留します。承認と戻す方法を記録します。署名は脆弱性がないことを証明しません。

再現できる受け入れ事例

架空の例です。顧客や実際の観測結果を示すデータではありません。

事例の入力を見る

{
    "signature_valid": true,
    "digest_matches": true,
    "expected_signer": "approved-publisher",
    "observed_signer": "different-publisher",
    "expected": "hold_for_independent_confirmation"
}