API設計はAIに任せられるのか。残る約束という判断の塊

AIに「このエンドポイントのレスポンスを、もう少し使いやすい形に整えて」と頼むと、一瞬で新しいコードが返ってくる。入れ子になった配列はフラットになり、冗長に見えたフィールドは消え、構文として正しいJSONを返す実装がその場で完成する。テストも通る。けれど、それをそのまま本番に出した瞬間に何が起きるかは、AIの画面のどこにも表示されない。

エンドポイントの実装を書くことと、エンドポイントの形を決めることは、見た目は同じ作業に見えて、背負っている責任がまったく違う。前者は「動くかどうか」をその場で確かめられる。後者は、今はまだ見えていない呼び出し側との約束を背負っている。

構文は検証できるが、約束は検証できない

実装を書く作業では、入出力の形があらかじめ決まっている。だからリクエストを一度投げれば、返ってきた値が期待どおりかはその場で白黒がつく。手早く正誤が確定する仕事こそ、AIが最も速く肩代わりできる部分だ。外したら投げ直せばいいだけで、やり直しの代償も軽い。

ところがAPIの設計——エンドポイントにどんな名前を与え、責務の線をどこで引き、レスポンスをどんな形にするか——には、その場で白黒のつく正誤がない。公開した瞬間、その形は「これからもこう受け取り、こう返す」という宣言になり、まだ存在しない呼び出し側との約束に変わる。約束が妥当だったかは、半年後に仕様を変えようとして初めて跳ね返ってくる。AIが見ているのは目の前の要求だけで、その要求を出していない将来の利用者の都合までは、最初から視界に入っていない。

後方互換という約束が破られた夜

あるチームが、注文APIのレスポンスを「使いやすく」整理し直したとする。入れ子になっていたitems配列をトップレベルに展開し、冗長に見えたstatus_codeフィールドを削除した。社内のフロントエンドは翌日から新しい形で問題なく動き、テストもすべて通っていた。

ところが、このAPIを別の用途で呼んでいた夜間バッチは、消えたstatus_codeフィールドを見て注文の完了を判定していた。フィールドがなくなった瞬間、バッチは例外を一つも出すことなく、黙って「未完了」と解釈し続けた。実装のバグなら、たいてい例外か400番台のエラーとしてすぐに姿を現す。ところがこれは、構文的には正しいレスポンスのまま、意味だけが静かにすり替わった状態だ。エラーは出ないまま夜間バッチは動き続け、翌朝、処理されるはずだった注文がまとまって「未処理」のまま積み残っていることに、別のチームが気づいて初めて発覚した。

実装のミスはエラーという形で自分の存在を主張してくれる。設計の約束違反は、構文上は何も壊れていないため、誰かが結果のおかしさに気づくまで、静かに下流を壊し続ける。これが、クエリの書き間違いとAPIの約束違反の、一番大きな非対称だ。

名前と境界にも、同じ構図がある

後方互換だけでなく、命名や境界にも同じ種類の判断が潜んでいる。/users/{id}/ordersと/orders?user_id={id}は同じデータを取得できるが、前者は「ユーザーに紐づく注文」という所有の構造を表し、後者は「注文という集合を絞り込む」という検索の構造を表す。どちらを選ぶかは、ユーザーと注文のどちらを主役として扱いたいかという理解に依存し、AIはどちらの構文も等しく正しく書けてしまう。

境界も同様だ。注文を作成するAPIが在庫の減算まで一つのレスポンスで返すべきか、別のAPIに分けるべきか。一つにまとめれば呼び出しは楽になるが、在庫のロジックが変わるたびに注文APIまで影響を受ける。どちらも「動く」コードは書けるが、将来の変更に強いのはどちらかは、実行結果では測れない。どちらの構文も等しく動いてしまうからこそ、選ぶ側に判断の基準がなければ、APIは少しずつその場しのぎの寄せ集めへと崩れていく。

実装の前に、約束を評価する目を持つ

エンドポイントの構文は、必要になったときにAIに聞けばその場で返ってくる。だが「この変更で、誰が困るか」「この境界を崩したら、どの呼び出し側が壊れるか」を評価する基準は、AIに代わりに判断してもらえない。この基準を持たないまま実装だけを練習した学習者は、AIが出してきた"改善"をそのまま採用するしかなくなる。採用した変更がのちに外部のチームを巻き込んで壊れたとき、原因が設計にあると気づけず、実装の書き方のほうを疑ってあちこち直そうとする。根本の約束が歪んでいる限り、同じ不具合は形を変えて出続ける。

では限られた学習時間を、構文の暗記と約束を評価する目のどちらに先に充てるか。これは好みの問題ではない。構文のほうは必要になればAIがその場で埋めてくれるが、「この形に決めたら誰の何が縛られるか」を読む目だけは、本人の中にしか育たないからだ。順番としては、ルーティングやハンドラの書き方を追いかける前に、命名・境界・後方互換・エラー契約を自分の言葉で良し悪し判定できる土台を先に置く。そのほうが、同じ時間の投資でも後からの効きが違う。昨夜の例に引き戻せば、レスポンスからフィールドを一つ削るとき「これを頼りに動いている誰かの夜間処理はないか」と一拍置けるか——その小さな立ち止まりを持てるかどうかが、AIが実装を量産する時代に残っていく差になる。

tasklogは、どの技術書や教材が現場でどれだけ引用されているかを集計したサイトだ。設計の芯を据える一冊に迷ったら、その積み上がりを手がかりにしてほしい。

https://s-tasklog.com/books/general