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

内部の関数呼び出しは、呼び出す側と呼ばれる側が同時に更新される。API 越しの呼び出しは、そうではない。この一点の違いが、設計上のほぼすべての制約を生む。

境界が固定されるということ

組織内のモジュールを API として公開すると、それは他チームの前提になる。以後、その振る舞いを変えることは、自分たちの都合だけでは決められない。よく知られた事例として、Amazon が社内のすべてのチームにサービス境界を API 経由に限定するよう指示したという話がある。この経緯は2011年に Steve Yegge が公開した回想として広く読まれてきたもので、一次的な社内文書として公表されているわけではない点は注記しておく。

重要なのは逸話の真偽ではなく、そこで生じる構造である。境界を API にすると、呼び出し側の変更速度と呼ばれる側の変更速度が分離される。分離は利点であり、同時に制約でもある。

REST が述べていること

Roy Fielding が2000年の博士論文で提示した REST は、ネットワークベースのソフトウェアアーキテクチャに課す一連の制約として定義されている。統一インターフェース、ステートレスな通信、キャッシュ可能性、階層化システム。いずれも、規模を拡大する際に何を犠牲にして何を得るかについての主張である。

実務で「REST API」と呼ばれるものの多くは、この制約集合のうち一部だけを採用している。それ自体は必ずしも誤りではない。ただし、採用しなかった制約が守っていたはずの性質は失われる。ステートレス性を放棄すれば水平分割が難しくなり、統一インターフェースを崩せばクライアントの結合度が上がる。

寛容さの代償

Jon Postel の名で知られるロバストネス原則は、「送信は厳格に、受信は寛容に」と要約される。この助言は初期のインターネットで相互接続を成立させるのに寄与した。

一方で、IETF は2023年に RFC 9413「Maintaining Robust Protocols」を公表し、この原則を無条件に適用することの危険を整理した。受信側が仕様外の入力を黙って受け入れると、送信側の実装は仕様から逸脱したまま動作し続ける。逸脱は蓄積し、やがて「実装が仕様である」状態に至る。そこから仕様を修正しようとすると、既存の接続が壊れる。

寛容さは、短期の接続性と長期の進化可能性を交換している。どちらを取るかは、その API が何年生きる想定かによる。

反論：厳格さは採用を妨げる

ただし、厳格な検証を最初から課せば、統合の初期コストは上がる。実際、外部の開発者に採用されることを目的とする公開 API では、多少の寛容さが普及を助けてきた。原則を一律に適用するのではなく、内部 API と公開 API で方針を分けるという整理のほうが実態に近い。

内部 API は利用者が特定でき、破壊的変更の調整が可能である。公開 API はそうではない。同じ「API」という語で呼ばれていても、変更に関する制約はまったく異なる。

仕様がないものは数えられない

OpenAPI 仕様のような機械可読な記述は、単に文書生成のためのものではない。それは、依存関係を静的に走査できる形にするための前提である。

ここで供給網の議論と接続する。SBOM が捉えるのはビルド時にリンクされたライブラリであって、実行時に呼び出される外部エンドポイントではない。API 依存は部品表に現れない。にもかかわらず、その可用性と振る舞いに自社のサービスは依存している。

依存の一覧を作ろうとするなら、ライブラリと API を同じ台帳に載せる必要がある。そして API 側には、ライブラリにはない属性が付く。相手方が仕様を変える権利を持っている、という属性である。この非対称性を明示的に扱わない設計は、可視化の対象から最も変わりやすい部分を落としている。指標の定義を一箇所に集めるセマンティックレイヤーの発想が、API 契約の管理にも応用されつつあるのは、この事情による。