社内向けAPIチェンジログ：他チームにとって何が変わるか
1分で読めます
このハブの他の記事はすべて、APIを呼び出す側が社外にいることを前提としている。顧客のエンジニア、パートナー、ドキュメントを自力で見つけた誰かだ。多くのAPIにはまったく異なる種類の呼び出し側がいる。隣の部屋にいる、あるいは二フロア先にいるチームだ。それはチェンジログが彼らに対して負う責任の計算を変える。Slackのメッセージなら彼らに届くし、サポートチケットが起票されることは通常まったくないからだ。多くのチームはここから、社内APIにはチェンジログが不要だという結論を導き出す。実際に必要なのは、異なるチェンジログだ。
社内APIのチェンジログが公開のものと何が違うのか
公開APIチェンジログには暗黙の読者がいる。そのAPIが構築する唯一のものを使う全員だ。社内APIの読者は直接連絡が取れる相手であり、それは公開APIチェンジログの大半が存在する主な理由、つまり個別に連絡できない呼び出し側への発信という理由を取り除く。社内APIを所有するチームは通常、どの他チームがそれを呼び出しているか、時には特定のサービスまで正確に把握している。それは公開フィードではなく的を絞ったメッセージを自然なデフォルトにし、だからこそ社内APIはチェンジログをまったく持たずに終わることがとても多い。所有チームは覚えている二、三のチームに知らせ、それで全員をカバーしていると思い込むのだ。
| 公開APIチェンジログ | 社内APIチェンジログ | |
|---|---|---|
| 誰が読むか | 直接連絡できないことが多い、任意の外部呼び出し側 | 通常は把握されている、小規模な社内チームの集合 |
| デフォルトのチャネル | ページとフィード | 呼び出し側チームへのメッセージ、理想的にはページも |
| 最大のリスク | 呼び出し側が項目を完全に見逃す | 所有チームが存在を覚えていない呼び出し側を忘れる |
| 「誰が呼んでいるか分からない」の代わりになるもの | 何もない。広く公開するだけ | 常に最新に保たれた、呼び出し側の本物の台帳 |
なぜ「呼び出しているチームにだけ知らせる」は崩壊するのか
呼び出し側の集合は、所有チームが記憶しているほど小さくも静的でもないからだ。一つの利用者のために構築されたサービスは、半年後に誰も発表しなかった統合を通じて二番目の呼び出し側を得て、所有チームの頭の中の「誰が我々を呼んでいるか」というリストは、誰も気づかないまま間違ったものになる。この失敗はありふれたもので珍しくない。記録の代わりに記憶に頼ることの当然の結果であり、誰かが不注意だった証ではない。breaking changeとは何かは、そもそもAPIの変更が破壊的とみなされるかどうかをどう判断するかを扱っている。社内のケースは、その上に誰に知らせるべきかを知るという、より難しい二つ目の問いを付け加える。
社内APIはそもそも公開スタイルのチェンジログページを必要とするのか
主要なチャネルが直接的であっても、たいていは必要だ。ページがあれば直接のメッセージにリンク先ができるので、通知は短く済む（「/v2/accountsにbreaking change、詳細はこちら」）。スクロールで消えていくチャットメッセージに全説明を詰め込もうとする必要はない。それはまた、新しいチームや直接のメッセージを見逃したチームが、自分たちの統合が壊れて理由を突き止めようとするときに確認できるものにもなる。ページは磨き上げられている必要も公開である必要もない。リンク可能であり、それを発表したSlackスレッドより長く生き残る必要があるだけだ。
呼び出し側のリストを実際に維持するのは誰か
所有チームであり、これは部族知識ではなく本物の成果物として扱われなければならない。最も安価なバージョンは、API自体のリポジトリ内のファイルで、新しい統合が構築されるたびに更新される、エントリごとに担当者が付いた消費側サービスの短いリストだ。あらゆる依存関係宣言と同じ規律である。代替案である、breaking changeのたびに周囲に聞いて回るというやり方は、誰かが適切な人に聞くのを一度忘れるまでは機能する。あるチームのために静かに壊れる社内APIは、公開のものより小さなインシデントだが、それでもインシデントであり、通常はAPIの所有者ではなくそのチーム自身のオンコールによって発見される。
# consumers.yml
- service: billing-service
owner: "#team-billing"
since: 2026-03-01
- service: reporting-pipeline
owner: "#team-analytics"
since: 2026-06-14このようなファイルは「誰に知らせなければならないか」を問いから検索に変える。まさにこの問題の ために作られたツール、例えばBackstageのサービスカタログ は、同じ理由からAPIを宣言された利用者を持つ第一級のエンティティとしてモデル化する。組織内の サービスが十分に増えれば、誰が何を呼んでいるかについての記憶はもはや自然には正確であり続けず、 代わりに何かが記録を保持しなければならなくなるからだ。すでに社内で使っているツールのドキュメント を確認するのが、自前のものを一から作る前にたいてい正しい出発点になる。
社内向けチェンジログの項目に含まれ、公開のものには不要なものは何か
より多くの運用上の具体性だ。読者は同じインフラストラクチャの中でこれに基づいて行動する別のエンジニアであり、要約として読むわけではないからだ。変更がどの環境でいつライブになるか。社内サービスは公開の呼び出し側が決して目にしない段階を経て昇格することが多いからだ。変更が消費側での設定やクライアントライブラリの更新を必要とするかどうか、あればコマンドとして表現されたもの。そして、社内の呼び出し側はしばしば所有チームと直接修正を調整できるため、サポートチャネルの代わりに名前を挙げた連絡先。「これが何か壊したら@mariaに知らせて」は社内向けの項目では完全に理にかなった一行だが、公開APIチェンジログでは奇妙な一行だ。
これはモノレポ内のチェンジログにも同じように当てはまるのか
置き換えるのではなく、同じ問題を鋭くする。モノレポのチェンジログは、パッケージがいつ独自のチェンジログを必要とするかを扱っている。モノレポ内の複数パッケージの一つである社内APIも、その消費者が明示的に追跡される必要がある。呼び出し側と同じリポジトリを共有していても、何かが見るように指示しない限り、彼らが変更に気づくとは限らないからだ。リポジトリ内の近さは、注意における近さと同じではない。
FAQ
呼び出し側が一つしかない場合、純粋に社内向けのAPIにチェンジログは必要か? ほとんど必要ない。その一つのチームへの直接のメッセージで通常は十分だ。呼び出し側が一つより多くなった時点、あるいは呼び出し側のリストが所有チームを一度でも驚かせた時点で、チェンジログは元が取れるようになる。それは記憶だけではもう信頼できないという合図だからだ。
社内APIの変更は公開のものと同じレビューを経るべきか? 読者が外部の呼び出し側ではなく同僚であるため、言葉遣いはより軽くてもよいが、変更が破壊的かどうかの判断はどちらの場合も同じ注意を払う価値がある。社内の呼び出し側にも、古い動作に依存する本番コードは存在する。
一度も追跡されていない場合、誰が社内APIを呼び出しているかをどう突き止めるか? 消費者の台帳が一度も維持されていなかった場合、サーバーログやサービスメッシュのトラフィックデータが正直な答えだ。その発見を、一回限りの片付けとしてではなく、台帳を始める瞬間として扱おう。
Slackのメッセージで十分か、それとも社内の変更にも正式なチェンジログの項目が必要か? 純粋に追加的でないものすべてについては、両方必要だ。メッセージは時間通りに読まれるものであり、項目は何週間も後に問題を調査していてメッセージを一度も見たことのないチームが、それでも見つけられるものだ。
この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。