API移行ガイドをどう書けばいいか、その方法

API移行ガイドは、互換性のない変更を障害ではなくチェックリストに変える文書だ。何が変わったか、それについて何をすべきか、そしていつまでに。チェンジログのエントリは互換性のない変更を二文で名指しできるが、移行ガイドは、その二文が「これはあなたを壊す」と言っていて、正確に何を編集すべきか知る必要があるときに、呼び出し側が実際に開くものだ。ガイドなしでエントリを公開することは、呼び出し側がそれを防ぐために書かれた文書からではなく、サポートチケットから互換性のない変更を知る方法だ。

API移行ガイドとは何か

呼び出し側をAPIの古い形から新しい形へと導く、段階的な文書であり、まだAPIを採用するかどうか決めている人ではなく、変更すべきコードを持っている人のために書かれる。この区別は重要だ。移行ガイドは既存の統合と既存の本番トラフィックを前提とするため、ロールバック、部分的な移行、そして移行が成功したかどうかをどう知るかをカバーしなければならず、そのどれも最初の統合のためのガイドには必要ない。

移行ガイドは通常、後者の二つの間に位置する。非推奨化通知は時計を作動させ、移行ガイドは呼び出し側がその時計が切れる前に従うものだ。

変更がチェンジログのエントリだけでなく移行ガイドを必要とするのはいつか

古い挙動と新しい挙動の間に複数のステップがあるとき、あるいは変更が十分多くの呼び出し箇所に触れていて、呼び出し側が説明よりも実例から利益を得るときだ。互換性のない変更とは何か、それをどうリリースするかがその変更が互換性のないものかどうかのテストを扱っている。答えがイエスなら、次の問いは修正が一行の編集なのか本物の移行なのかだ。名前が変わったフィールドなら、呼び出し側はチェンジログのエントリだけで対処できる。認証、ページネーション、エラー処理の変更はほとんど常にガイドに値する。なぜなら正しい代替コードが一文の説明からは明らかではないからだ。

移行ガイドは何を含まなければならないか

五つのことがあり、そのどれか一つを省くことが、呼び出し側が一度読んでその後は試行錯誤に戻ってしまうページにガイドを変えてしまう原因になる。古いコードを、実際にプロジェクトに現れる通りに示す。新しいコードを、同じように示す。違いの抽象的な説明としてではなく。何も変えなければ何が壊れるかを、はっきりと言う。なぜなら「何も」は妥当でよくある答えであり、それでも呼び出し側は明示的に聞く必要があるからだ。移行がうまくいったかを確認する方法、たとえば確認すべきレスポンスフィールドやステータスコード。そしてタイムライン。古い挙動がいつ動かなくなるか、そしてその間両方の形が利用可能かどうか。

## 通貨フィールドをfloatからintegerへ移行 (v3.0.0)

前:
  { "amount": 19.99 }

後:
  { "amount": 1999 }  // 最小通貨単位(セント)

何が変わるか: `amount`は今やアカウント通貨の最小単位での整数だ。
`amount`をfloatとして読むコードは、2026年10月1日から100倍大きすぎる
値を読むことになる。

確認: 移行後、19.99ドルの請求は`amount: 1999`と読まれるべきで、
`amount: 19.99`ではない。

タイムライン: v2は2027年1月15日までfloatを返し続ける。v3は起動から
整数を返す。両方のバージョンが今アクティブだ。

これら五つのそれぞれが、そうでなければ呼び出し側が推測するかサポートに尋ねなければならない質問に答えていて、それこそが移行ガイドが実際に節約するコストだ。

誰がそれを書くべきか、そしていつか

変更を設計した人が、それがリリースされるまさにその瞬間に。一週間後にチケットからそれを再構成するサポートチームではない。決定を下した人は、古い挙動のどの部分に誰も頼るべきでなかったか、どの部分が偶然の契約だったかを知っている。その文脈を持たない誰かが後から書いたガイドは、明白なことを過剰に説明するか、実際に人々を壊すたった一つのエッジケースを見逃す傾向がある。ガイドと、互換性のない変更を発表するチェンジログのエントリは一緒に出るべきで、エントリはそれを繰り返すのではなくガイドにリンクすべきだ。

これはバージョニングとAPIチェンジログにどう関係するか

直接的にだ。移行ガイドは、セマンティックバージョニングとあなたのチェンジログの中でMAJORのエントリが一文でしか要約しないものの詳細版だ。チェンジログのエントリは変更が互換性のないものであることと、大まかに何が変わったかを言う。移行ガイドは、そのエントリが運ぶべきリンクだ。APIチェンジログ: 何を公開し、誰が読むのかは移行ガイドを、APIが維持する五つの文書の一つとして挙げていて、それぞれが異なる質問に答えている。これは「実際にAからBへどう移行するか」に答えるものであり、その答えが通常チェンジログのエントリには長すぎるからこそ、独自のページに値する。

移行ガイドはどれくらいの期間公開され続けるべきか

少なくとも古い挙動が到達可能である限り、そして理想的にはその後も。三つの非推奨化通知を無視した後、十八か月遅れて移行する呼び出し側も、それでもガイドを必要としていて、古い挙動が停止するその日にそれを削除することは、それを最も必要とする呼び出し側がそれを見つけられないことを保証するだけだ。安定したURLに保ち、ページを撤回する代わりにタイムラインのセクションを更新すること。Stripeのアップグレードガイドは、このパターンの公開されている実例だ。バージョンごとに新しい文書を作り、次のバージョンが出た瞬間に古びてしまうのではなく、一つのページをリリースのたびに最新の状態に保っている。自分のガイドも同じくらい見つけやすい場所に置くべきで、ブログのアーカイブに埋もれさせるのではなく、呼び出し側がすでに読んでいるドキュメントのそばに置くのがよい。

FAQ

すべての互換性のない変更に移行ガイドが必要か? いいえ。呼び出し側がチェンジログのエントリだけで対処できる変更、たとえば明白な代替を持つ単一の名前変更フィールドは、別のガイドを必要としない。複数の呼び出し箇所に触れる変更や、実例を必要とする変更には必要だ。

移行ガイドはAPIのドキュメントと一緒にあるべきか、それともチェンジログにあるべきか? ドキュメントと一緒に、チェンジログのエントリからリンクされて。エントリは購読者が最初に見るものであり、ガイドは行動を起こすと決めた瞬間に必要とするものであり、呼び出し側がすでに使っている参照資料の隣に属する。

移行ガイドと非推奨化通知の違いは何か? 非推奨化通知は何かがなくなること、いつまでかを述べる。移行ガイドはそれについて何をすべきかの指示だ。リンクされた移行ガイドのない非推奨化通知は、呼び出し側に期限を与えながら、それをどう守るかを伝えていない。

移行期間中、古い挙動と新しい挙動の両方を文書化すべきか? はい、可能なら同じページで。呼び出し側が何が変わったかを正確に見られるようにするためで、異なる時期に書かれた二つの別々の文書からそれを組み立てるよりも良い。

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

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