前回との接続と、この講義の役割
N-03では、経費データを何をどう保存するかを設計書にまとめました。今回は、その保存とデータのやり取りをつなぐ通り道、APIの設計に進みます。K-02では、APIは呼ぶ側と応える側の約束、つまり契約であると学びました。この契約は一度使われ始めると、勝手に変えると相手側が動かなくなります。今回はその契約に、時間が経っても相手を壊さないための「互換性」という設計の観点を加えます。
このスライドのポイント
- N-03: 経費データの保存の仕方を設計書にまとめた
- 今回: その手前と奥をつなぐ通り道＝APIの設計へ
- K-02で学んだ「契約」に、時間が経っても壊さないための「互換性」を加える
API設計の定義——契約に互換性を足す
API設計とは、K-02で学んだ契約の6項目、つまり機能の境界、入力、出力、認証、エラー、呼び出し方を決めることに加えて、互換性を設計することです。互換性とは、すでにそのAPIを使っている側を壊さずに変更できる性質のことです。応答に項目を足す、新しいエンドポイントを追加する、といった変更は既存の利用側に影響しないため、壊さない変更と呼びます。反対に、項目の削除、改名、型変更、入力の必須化は、使う側を止めてしまう壊す変更です。壊す変更を行うときは、バージョンを分けるなどの移行設計が必要になります。
このスライドのポイント
- API設計＝K-02の契約6項目（機能の境界・入力・出力・認証・エラー・呼び出し方）を決めること＋互換性を設計すること
- 互換性＝すでにそのAPIを使っている側を壊さずに変更できる性質
- 壊さない変更: 応答に項目を足す／新しいエンドポイントを追加する
- 壊す変更: 項目の削除・改名・型の変更・入力の必須化
- 壊す変更はバージョン分けなどの移行設計が必要
なぜ互換性を設計するのか
互換性を設計に織り込まないと、「APIをちょっと直しただけなのに、画面側が全部動かなくなった」という事故が起きます。これは、K-02で学んだ契約を、相手に断りなく一方的に書き換えてしまった状態です。やっかいなのは、AIは頼まれた変更を素直にそのまま実行するという点です。「この項目、名前を変えて」と頼めば、それを使っている側がどうなるかを気にせず改名します。ですから、その変更が誰を壊すかを見張る互換性の番人は、人間が担う仕事になります。
このスライドのポイント
- 互換性を知らないと: 「APIをちょっと直したらフロントが全部壊れた」が起きる
- これはK-02の契約を、相手に断りなく一方的に変えてしまった状態
- AIは頼まれた変更を素直に実行する。互換性の番人は人間
変更の2分類——約束を変えるなら通告と移行期間
変更は、壊さない変更と壊す変更の2つに分けると整理できます。壊さない変更は、基本的に「足すだけ」の変更です。応答に項目を足す、新しいエンドポイントを追加する、といったものは、既存の利用側が無視できるので、そのまま出して構いません。壊す変更は、削除・改名・型変更・入力の必須化のように、相手の前提を崩す変更です。契約を約束にたとえるなら、約束を変えるときは相手に前もって通告し、切り替えの移行期間を渡すのが筋です。壊す変更には、この通告と猶予をセットで設計します。
このスライドのポイント
- 変更は「壊さない変更」と「壊す変更」の2つに分けて考える
- 壊さない変更: 追加だけ（応答に項目を足す・新エンドポイント）→そのまま出してよい
- 壊す変更: 削除・改名・型変更・必須化→相手への通告と移行期間が要る
- 比喩: 契約は約束。約束を変えるなら、相手に前もって伝え、切り替えの猶予を渡す
経費APIでの具体例
経費精算アプリで具体的に見てみましょう。まず壊さない変更です。応答に費目を表すcategoryという項目を新しく足しても、その項目を使っていない画面側はただ無視すればよいので、誰も壊れません。次に壊す変更です。金額を表すamountという項目をamount_yenに改名すると、旧名を読んでいた画面側は金額を受け取れず動かなくなります。ですから、当面は旧名のamountもあわせて返し、新旧が並ぶ期間を設けます。すべての利用側が切り替わったことを確認してから、旧名を外します。
このスライドのポイント
- 壊さない例: 経費APIの応答にcategory（費目）項目を足す→使っていない側は無視できる
- 壊す例: amount（金額）をamount_yenに改名する→そのままだと旧名を使う側が落ちる
- 壊す変更の進め方: 旧名amountも当面あわせて返す／新旧が並ぶ期間を設ける／全員が切り替わったら旧名を外す
技術サンプルカード——壊す/壊さないの判断表
この表は、よくあるAPI変更を壊す変更か壊さない変更かで分け、それぞれの対処を並べたものです。読み方は単純です。「足すだけ」の行は壊さない側、項目を削る・改名する・型を変える・入力を必須にする行は壊す側です。注目してほしいのは、壊す側の対処が必ず通告か移行期間を含む点です。AIに変更を頼むときは、この表を渡したうえで「このAPI変更は既存の利用側を壊しますか。壊す場合の移行手順を提案してください」と聞くと、判断と手順を一緒に引き出せます。
このスライドのポイント
- 種別: table
- 目的: よくあるAPI変更が、壊す変更か壊さない変更かと、その対処を一目で判断する
- サンプル本体:
混同しやすい概念——「動く変更」と「壊さない変更」
ここで混同しやすいのが、「動く変更」と「壊さない変更」の違いです。動く変更とは、自分の手元の環境でAPIが動いている状態のことです。一方、壊さない変更とは、そのAPIを使う利用側全員にとって、これまで通り動き続ける状態です。この2つは別物です。自分の環境で項目を改名し、自分のテストが通っても、その名前を使っていた別の画面は落ちているかもしれません。B-06で学んだ「ローカルで動くことと本番で動くことは違う」という話の、API版だと考えてください。
このスライドのポイント
- 「動く変更」: 自分の環境でAPIが動いている状態
- 「壊さない変更」: 利用側全員にとって、これまで通り動く状態
- 自分の手元で動いても、既存の利用側を壊していれば壊す変更
- B-06「ローカルで動く≠本番で動く」のAPI版
バイブコーディングでの確認点
バイブコーディングでの確認点は、順番が大事です。APIの変更をAIに頼むときは、いきなり直させるのではなく、まず「この変更で影響を受ける利用側をすべて列挙してください」と先に依頼します。影響を受ける相手が分かって初めて、その変更が壊す変更か壊さない変更かを判断できるからです。これは、A-09で学んだ、変更の前に影響範囲を確認するという習慣のAPI版です。AIは影響範囲を気にせず変更を実行しますから、その一歩手前で人間が影響先を洗い出すことが、互換性を守る鍵になります。
このスライドのポイント
- API変更をAIに頼むときは、まず「この変更で影響を受ける利用側を列挙して」を先に依頼する
- 影響範囲を確認してから、壊す/壊さないを判断する
- A-09で学んだ「影響範囲の確認」のAPI版
まとめと次回への橋渡し
最後に一問一答です。応答から項目を削除するのは、壊す変更と壊さない変更のどちらでしょうか。……答えは、壊す変更です。その項目を読んでいた利用側が受け取れなくなり、落ちてしまうからです。30秒でまとめます。API設計は、K-02の契約6項目に互換性を足して考えます。足すだけの変更は壊さず、削る・改名・型変更・必須化は壊します。壊す変更には、通告と移行期間をセットで設計します。次回は、部品の中を整理する術、責任分離へ進みます。関連資料は「API連携 超入門」と「PRD簡易テンプレート」です。
このスライドのポイント
- 一問一答: 「応答から項目を削除するのは壊す変更・壊さない変更のどちら？」→ 壊す変更（使っている側が落ちる）
- 30秒まとめ: API設計は契約6項目＋互換性。足すだけは壊さない、削る・改名・型変更・必須化は壊す。壊す変更は通告と移行期間を設計する
- 次回: 部品の中の整理術＝責任分離へ
- 関連資料: 「API連携 超入門」「PRD簡易テンプレート」
