APIチェンジログ: 何を公開し、誰が読むのか

APIチェンジログとは、呼び出し側が気づく可能性のあるすべての変更を日付付きで記録したもので、リリースするチームのためではなく、そのAPIと統合する人々のために書かれる。この読者層こそが、それを製品のチェンジログとは異なる文書にしている。読者は自分のコードが来月も動くかどうかを判断しているのだ。多くのAPIチェンジログは同じ理由で失敗する。内部のリリースフィードをフィルタしただけのコピーになっており、削除されたフィールドが文言修正と同じ重みで並び、どちらも読まれない。

APIチェンジログとは何か

これは、他人がそれに対してコードを書いたインターフェースへの変更を記録した、公開の日付付きログである。何かがそこに含まれるべきかどうかを判断する有用なテストは、その変更が内部でどれほど大きかったかとは無関係だ。テストが問うのは、去年書かれてそれ以来触れられていない正しい呼び出し側が、それによって振る舞いを変える可能性があるかどうかである。このテストは、非常に小さな変更のいくつかを受け入れ、非常に大きな変更のいくつかを除外する。

以下のすべては、呼び出し側が社外にいて、この文書以外では実質的に連絡が取れないことを前提としている。呼び出し側が同じ会社の別のチームである場合、その計算は独自の扱いに値するほど変わる。社内向けAPIチェンジログは、その読者が代わりに何を必要とするかを扱っている。

API移行ガイドの書き方がこの最後の文書を完全に扱っている。短く言えば、これは互換性のない変更のエントリが、それを置き換えようとするのではなくリンクすべきものだ。

この五つは、それぞれ別のライフサイクルを持つ別の文書である。非推奨化通知は日付付きの約束であり、チェンジログにも属するが、チェンジログのエントリは一度書かれるのに対し、非推奨化はそのサンセットまで追跡される。両者を混同することが、サンセットが見逃される原因になる。

一つのエントリに何を含めるべきか

六つのことがあり、最初の三つは通常欠けているものだ。変更内容を、内部コンポーネントではなくリクエストやレスポンスの言葉で述べること。正しい呼び出し側を壊すかどうか。呼び出し側が何をすべきか、「何もしない」を含めて。それが発効した日付。影響を受けるバージョンまたはバージョン群。存在するなら移行ガイドへのリンク。

「accountsエンドポイントを改善」というエントリは、六つすべてに失敗する。「accounts.typeフィールドは、以前はpersonalを返していたところで現在はindividualを返す。9月2日より前に作成されたアカウントでは既存の値は変わらない。文字列を比較しない限りアクションは不要」というエントリは、一文で六つすべてに答える。

エントリは部署ではなく結果によって分類すること。ほぼすべての価値を三つのラベルが担う。breaking、additive、fixedだ。Semantic Versioningはすでに最初の二つを正確に定義しており、独自の定義を考案する代わりにその定義を借用することは、semverを知る読者があなたのラベルを理解することを意味する。Keep a Changelogは望むならより長いセットを提供しており、その中心的な規則はここで他のどこよりも強く当てはまる。ログは人間のためのものであり、コミットタイトルの羅列はそうではない。

APIチェンジログはリリースノートとどう違うのか

リリースノートは製品が今何をできるかを説明する。APIチェンジログは契約が今どうなっているかを説明する。同じリリース作業がしばしば両方にエントリを生み出し、異なる文言で書かれる。読者層が異なるものを必要とするからだ。新しいエクスポート形式は、ユーザーにとっては機能だが、そのフィールドで分岐する呼び出し側にとっては新しいenum値である。

実際的な結果として、この二つは同じフィードにスタイルだけ変えたものにはできない。あなたが出荷するすべてに購読している呼び出し側は最終的に購読を解除し、そして破壊的変更を見逃すことになる。一つのフィードを公開するならフィルタすること。二つ公開するなら、APIのものを狭くし、マーケティングのエントリを決して入れないこと。両方の形を並べてチェンジログ対リリースノートで比較している。

APIチェンジログはどこにあるべきか

リファレンスドキュメントの隣に、安定したURLで、各エントリがフラグメントか独自のパスで個別にアドレス可能な形で。呼び出し側はインシデントレビューや社内チケットでエントリにリンクする。リンクできないエントリは、代わりにスクリーンショットとして貼り付けられることになる。

ページに加えて、機械可読な出力としても公開すること。JSON Feed仕様に従うJSONフィードやRSSフィードは、エントリが構造化データになれば何のコストもかからず、それこそが顧客が自分たちのリリースプロセスにあなたの変更を組み込めるようにするものだ。これはまた、誰かがその上に何かを構築するかどうかを決める部分でもある。GitHubは同じ理由でREST APIのバージョンをリファレンスのすぐ隣に文書化している。バージョンポリシーはインターフェースの一部だからだ。

実際に良いエントリはどう見えるか

同じ週の三つのエントリを、上記の形式で示す。

2026-09-02  Breaking  v2
  `POST /invoices` は、顧客のアカウント通貨と一致しない `currency` を
  拒否するようになり、暗黙に変換する代わりに422を返す。変換に依存し
  ていた呼び出し側は、アカウント通貨を送信する必要がある。v2のみに
  影響し、v1は2027-01-15のサンセットまで変わらない。

2026-09-02  Additive  v1, v2
  `Invoice` は、請求書が決済されるまでnullとなる `settled_at` タイム
  スタンプを得る。アクションは不要。未知のフィールドを拒否するクラ
  イアントは更新すべき。

2026-08-31  Fixed  v2
  `GET /invoices?status=` は、未知のステータスに対して400ではなく
  空のページを返していた。現在は許容される値とともに400を返す。タ
  イプミスをした呼び出し側は、以前はゼロ件の結果を見ていたが、現在
  はエラーを見る。

三つ目は最もよく省略されるタイプだ。内部的にはバグ修正だからだ。その空のページを前提にリトライを組んでいた呼び出し側にとっては、これは振る舞いの変更であり、そのエントリこそがサポートチケットを防ぐものだ。ラベルはfixedと言い、本文は呼び出し側が気づくかもしれないことを述べている。これが、あらゆる修正を破壊的変更に膨らませることなくログを正直に保つ区別である。

呼び出し側はどう購読するのか

一つ以上のチャネルを与えること。彼らの仕事が異なるからだ。すべてを望む開発者向けのフィード。破壊的変更だけを望む人向けのメール。コード自体のためのレスポンスヘッダーは、確認を決して忘れない唯一の購読者だ。RFC 8594で定義されたSunsetヘッダーは、廃止日をレスポンスに置き、クライアントライブラリがそれをログに記録できるようにする。

多くのチームが省略するチャネルは直接のものだ。ある呼び出し側が先週、あなたが変更しようとしているフィールドを使っていたなら、それが誰かはわかっている。そのアカウントへのメールは、どんな一斉配信よりも価値がある。これは、誰も要求していない変更に適用された顧客フィードバックループを閉じることと同じ規律だ。影響を受けた人々には個別に伝え、それ以外の全員にはフィードが届く。Webhookは、頼る前に知っておく価値のある独自の失敗の仕方を持つ第四のチャネルだ。Webhookチェンジログは、そこでのペイロード変更が、新しい形式を拒否できる呼び出し側なしに静かに壊れる理由を扱っている。

破壊的変更のエントリはどう書くべきか

理由からではなく、破壊そのものから始めること。十件のエントリをスキャンする呼び出し側は、最初の一文で、それが自分の作業を発生させるかどうかを知る必要がある。次に日付、影響を受けるバージョン、移行方法、そして古い振る舞いが変化するのではなく消える場合の期限。

同じ内容を非推奨化通知、レスポンスヘッダー、直接のメールに、一貫した文言で入れ、四つすべてに同じ日付を与えること。それらの間のずれは、計画された変更をインシデントに変えてしまう失敗だ。一つしか読んでいない呼び出し側が、誤った日付に基づいて行動してしまうからである。破壊的変更とは何かはその決定自体を扱い、APIの非推奨化方法はその後に続くスケジュールを扱う。

changeloopでは、プルリクエストがマージされ、誰かがドラフトを編集して承認し、フィードとウィジェットに公開されたとき、API変更がエントリになる。その同じ瞬間に、ウィジェットのフィードバックがGitHub issueになり、そのissueをプルリクエストがクローズする呼び出し側には、そのissue上で通知が届く。ここで重要なのはレビューのステップだ。APIチェンジログは契約文書であり、人間が読んでいないドラフトが呼び出し側に届くべきではない。

FAQ

すべてのAPI変更にチェンジログのエントリが必要か? 正しい呼び出し側が気づく可能性のある変更はすべて必要だ。内部的だと考えているものも含む。リクエストやレスポンスに観測可能な効果がない変更は不要で、それを追加すると読者に流し読みを訓練してしまう。

APIチェンジログはドキュメントとマーケティングサイトのどちらにあるべきか? ドキュメントの、リファレンスのすぐ隣。読者は通常すでにそこにいて、マーケティングサイト上のチェンジログは、それが書かれた対象ではない読者を獲得しがちだ。

どこまで過去に遡るべきか? 無期限に。エントリは何年も後にインシデントレビューで引用され、切り詰められたログはそのリンクを壊してしまう。削除ではなくページ分割すること。

APIバージョンごとに別のチェンジログが必要か? 不要だ。エントリごとにバージョンフィールドを持つ一つのログの方が、読むのも検索するのも簡単だ。バージョンによるフィルタはページの機能であり、文書を分割する理由ではない。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： 開発者向けドキュメント, changelogの例