API が基盤になるとき、何が固定されるのか

組織の境界を超えて公開される API は、内部 API とは別の設計制約を負う。この違いは技術ドキュメントであまり議論されない。REST か GraphQL かという選択の背後に、後方互換性、非推奨化、レート制限という三つの判断が隠れていて、実質的にはそちらがサービスの寿命を決める。内部 API を外部 API へ転換する組織が繰り返し同じ場所で失敗するのは、そのためだ。

後方互換性を運用可能な形で定義する

「破壊的変更を避けよ」という原則は実装レベルで曖昧すぎる。新しいフィールドの追加は破壊的か。既存フィールドの意味の変更は。レスポンスの順序変更は。答えは呼び出し側の実装に依存し、API 提供者からは判定できない。

Google の API Improvement Proposals が採るアプローチは、変更可能な項目と変更不可能な項目を明示的にリスト化することだ。エンドポイント URL、フィールド名、フィールド型、必須性、デフォルト値、エラーコード。このうちどれが後方互換性を保証されるのかを、API 契約の一部として文書化する。

定義があれば、実装変更の判断は「破壊的か」ではなく「契約された不変項目に触れるか」で下せる。判定基準が主観から機械的な照合に変わる。依存関係のリスク管理と同じく、項目ごとの明示化がガバナンスを成立させている。セマンティックレイヤーの設計で指標定義を契約として扱うのも、発想としては同じ系列にある。

非推奨化を律速するのは顧客のカレンダー

API のバージョン移行は、多くの組織でサポート期限を設定するという技術判断として扱われる。実際に律速するのは顧客側の移行速度のほうだ。

BtoB API の場合、顧客は自組織の開発ロードマップ内で移行を計画する。これは通常、四半期単位のプロセスになる。「6ヶ月後にサポート終了」という通知は、多くの顧客にとって「次の予算サイクルまで待って対応する」という判断を意味する。技術的には十分な猶予に見えても、相手の意思決定サイクルに乗らなければ猶予として機能しない。

この現実を踏まえるなら、非推奨化スケジュールは移行に必要な通信サイクル数で設計すべきだろう。初回警告、中間リマインド、最終警告という最低3回の通知が入る期間、多くの場合12から18ヶ月が必要になる。短縮すれば大口顧客が対応できず、契約リスクとして跳ね返る。古いコードを早く退役させたいという技術的な理想と、契約上の現実がここで衝突する。

レート制限を SLA として書く

レート制限を悪意ある利用者からの防御として実装している API は、正常な顧客の体験を悪化させる。実際にレート制限に引っかかる相手の多くは攻撃者ではなく、通常業務の負荷が想定を超えた正規利用者だからだ。

正しい認識は、レート制限は SLA の一部である、というものになる。顧客は制限値、超過時の挙動、そして超過を予期する方法を契約時点で理解する必要がある。429 応答を返すのか、キューイングするのか、優先度を下げるのか。Retry-After ヘッダーや残量ヘッダーはあるのか。この情報を提供せずに実装されたレート制限は、顧客から見て予測不能な障害として現れる。

階層別のレート制限を導入するなら、階層間の境界と再交渉可能性を明示することが契約上の重要事項になる。ここを曖昧にすると、顧客の成長がそのままレート制限違反として現れ、営業からのエスカレーションが常態化する。

OpenAPI 仕様書を公開すればこれらは形式的に伝達される、という反論はあるだろう。多くの現代的な API は実際に仕様書を公開している。ただし仕様書の存在と、それが契約として扱われることは別の話だ。仕様書が実装から自動生成される運用では、それは実装の状態を反映するだけで、契約としての安定性を保証しない。契約としての仕様書は実装と独立に管理され、変更にレビューと通知プロセスを伴う。この体制がないまま仕様書だけ公開しても、契約としては機能しない。

結局、内部 API を外部公開する判断は技術的な準備よりも契約的な準備で律速される。後方互換性の項目リスト、非推奨化の通信サイクル、レート制限の SLA 化。実装するには法務、営業、カスタマーサポートを含む横断的な調整がいる。調整コストを軽視した外部公開は、しばしば公開後1年から2年で「本番停止できないレガシー API」として組織の重荷になる。