これは何か
API互換性・版管理方針は、システム同士がやりとりする窓口（API）の形を変えるとき、どんな変更なら相手に影響がなく、どんな変更なら相手に知らせて移行の期間を置き、古い形をいつまで残していつやめるかを決めた成果物です。
API は、システムが外に見せる「約束」です。約束の形を黙って変えると、相手のシステムが壊れます。約束を永遠に変えないこともできません。だから、変え方の決まりが要ります。07-02 APIは万能ではない で学んだ連携の難しさの多くは、この「変え方」に関わります。
なぜ作るか
- 送り手の変更で受け手が壊れる事故を防ぐ
- 変えてよいことと、知らせてから変えるべきことを、会社の間で同じ基準にする
- 古い形をいつまで残すか（移行の期間）を決め、永遠に古い形を支え続ける負担を避ける
- 約36本の連携を複数の会社が担当する状況で、変更の手続きをそろえる
誰が使うか・いつ作るか
- 作る人：システムアーキテクトと、連携の基盤を担当する会社。各連携の送り手・受け手の会社が合意する
- 使う人：連携を実装する開発者、連携の仕様を書く人、変更を承認する人、テストの担当
- 一般的には、連携の設計が始まる前に決め、最初の仕様変更が起きたときに手続きを見直します
- アステリア案件の API の版の付け方、互換性の規則、古い形を残す期間は、正本に記載がありません。未確定
CASE FACTFROZEN正本に記載されたアステリア案件の事実
連携に関係する記載
- 約36本のシステム連携。正本で個別に定義された連携は IF-01〜IF-12
- 連携の経路には SYS-06 システム連携基盤を通るもの（IF-04 工数連携、IF-05 売上仕訳連携、IF-07 原価仕訳連携 など）と、直接つなぐもの（IF-01 顧客マスター連携、IF-02 契約情報連携 など）がある
- Vendor B クラウドブリッジの担当範囲に 連携 が含まれる。Vendor A は新基幹アプリケーション、Vendor C は FIN-CORE、会計連携
- P-008 黒田 健 — システムアーキテクト
各連携の API の形、版、変更の手続きは、正本に記載がありません。未確定
主な項目
一般的には、次の項目で構成します。
- 版の付け方：版の番号の形と、どこに表す（窓口の住所、やりとりの見出し など）か
- 互換性の分類：相手に影響のない変更（項目の追加、任意の項目の追加 など）と、影響のある変更（項目の削除、意味の変更、必須の追加、形の変更 など）の一覧
- 影響のある変更の手続き：新しい版を作り、古い版と並行して提供し、受け手に通知し、移行の期限を決め、期限後に古い版を止める
- 並行提供の期間：最短でどれだけ残すか。受け手の数と改修の見込みから決める
- 通知の方法：誰に、どの経路で、どれだけ前に知らせるか。受け手の一覧をどこで管理するか
- 確かめ方：互換性を壊していないことを、自動のテスト（TST-007 契約テスト仕様）でどう確かめるか
- 例外：安全上の理由で急いで変えるときの手続き
教材用サンプル成果物の読み方を学ぶための例
教材用サンプル — 互換性の分類と手続き
この成果物は学習用サンプルです。FROZEN正本に記載されたCASE FACTと、成果物の読み方を学ぶための教材用サンプル値を区別して表示しています。
次の表は、方針の書き方を学ぶための例です。内容はすべて教材上の架空の例で、アステリア案件の記録ではありません。
| 変更の種類（教材上の例） | 相手への影響 | 分類 | 手続き |
|---|---|---|---|
| 応答に項目を追加する | 受け手が知らない項目を無視すれば影響なし | 互換 | 通知のみ。版は変えない |
| 要求に任意の項目を追加する | 送らなくても今までどおり動く | 互換 | 通知のみ |
| 項目の名前や意味を変える | 受け手の処理が壊れる | 非互換 | 新しい版を作り、並行提供する |
| 必須の項目を追加する | 送っていない受け手が失敗する | 非互換 | 新しい版を作り、並行提供する |
| 項目を削除する | 使っている受け手が壊れる | 非互換 | 新しい版を作り、並行提供する |
| 返す誤りの種類を増やす | 受け手の誤り処理が想定外の値を受ける | 条件付き互換 | 受け手が未知の誤りを安全に扱う決まりがあれば互換、なければ非互換 |
| 段階（教材上の例） | 内容 | 期限の目安 |
|---|---|---|
| 1 通知 | 受け手の一覧の全員に、変更の内容・新しい版・古い版を止める予定日を知らせる | 止める日の 90 日前まで |
| 2 並行提供 | 新しい版を公開し、古い版も動かし続ける。受け手ごとの移行状況を一覧で追う | 最短 90 日 |
| 3 確認 | 古い版への呼び出しが残っていないかを記録で確かめる。残っている受け手に個別に連絡 | 止める日の 14 日前 |
| 4 停止 | 古い版を止める。止めた日と、最後まで残っていた受け手を記録する | 予定日 |
読み方
- 互換・非互換の分類が、具体的な変更の種類で書かれているか（「大きな変更は非互換」のような抽象では判断できない）
- 非互換の変更に、並行提供と通知と期限の手続きがあるか
- 受け手の一覧がどこにあり、誰が管理しているか
- 互換性を自動で確かめる仕組み（契約テスト）があるか
- 急ぐときの例外が、通常の手続きの抜け道になっていないか
書き方
- 連携の一覧（ARC-004 システム連携一覧）から、送り手・受け手・担当する会社を確かめる
- 互換性の分類を、変更の種類の一覧として書く。各社の設計者と読み合わせる
- 非互換の変更の手続きと期限を決め、受け手の一覧の管理者を決める
- 契約テストと結びつけ、分類の判断を自動化できる部分を決める
- 最初の仕様変更で手続きを実際に通し、直す
何を書いてはいけないか
- 「互換性に配慮して変更する」のような、判断基準のない決まり
- 期限のない並行提供（古い版が永遠に残り、負担だけが増える）
- 受け手の一覧なしの通知（誰に知らせたかが分からない）
- 実在の製品名を、案件の正式な採用として書くこと（正本に記載がない）
どこを見るか
- 互換・非互換の分類の具体性
- 非互換の変更の手続きと期限
- 受け手の一覧と管理者
- 自動で確かめる仕組み
- 例外の扱い
赤信号
- 送り手が「小さな変更」として黙って形を変え、受け手の連携が止まった
- 古い版が複数残り、どの受け手がどの版を使っているか誰も答えられない
- 受け手への通知が担当者の記憶に頼っており、一覧がない
- 急ぐときの例外が常態化し、通常の手続きを誰も通らない
よくある失敗
- 互換性の分類を決めずに開発を始め、最初の仕様変更で会社の間の責任の押し付け合いになる
- 並行提供の期間を決めずに新しい版を出し、古い版を止めるタイミングを永遠に失う
- 受け手の一覧を作らず、通知したつもりの受け手が実は一覧になかった
関係するUnit・成果物・危機演習
- Unit：07-08 APIの版をどう管理するか、07-02 APIは万能ではない、05-04 システム同士をどうつなぐのか、07-07 連携の約束をどうテストするか
- 成果物：ARC-004 システム連携一覧、ARC-005 システム連携処理図、TST-007 契約テスト仕様、PRG-008 変更管理台帳
- 危機演習：この成果物を直接の題材にする危機演習はありません
AI WORKFLOW
AIは、API の仕様の新旧 2 版を比べ、変更の種類を互換性の分類に当てはめる下書きに役立ちます。
「次の API 仕様の旧版と新版を比べ、変更された項目ごとに『変更の種類』（追加・削除・名前の変更・意味の変更・必須化・形の変更）を示し、添付の互換性の分類表に当てはめてください。分類表にない種類の変更は『分類なし』と示し、互換かどうかを推測しないでください。」
REVIEW
- AIが見つけた変更が、仕様の差分と一致しているか（見落とし、誤検出がないか）
- 「分類なし」の変更について、人が分類を決めたか
- API 仕様を AI に渡してよいか（相手の会社との守秘の扱い）を事前に確かめたか
人間が判断すること
- 互換性の分類の境目（条件付きの変更をどちらに扱うか）
- 並行提供の期間と、古い版を止める日
- 急ぐ変更の例外を認めるか
設計承認は、AIへ最終委任しない事項です（正本の方針）。
いつ使うか
この教材では STAGE 07｜36本のシステム連携を管理する の文脈で扱います。 アステリア案件での正式な作成・使用時期（月）は正本に記載がないため、未確定としています。
最後の問い
この方針を読んだ連携の担当は、「相手に影響を与えずに変えてよいこと」「相手に知らせて移行期間を置くべきこと」「絶対にしてはいけないこと」を、具体例つきで区別できますか？