2.3 APIとインターフェース設計

概要と動機

API(アプリケーションプログラミングインターフェース)とは、あるソフトウェアが別のソフトウェアに機能を提供する契約です。チーム、システム、組織が出会う場所であり、間違えると最も長続きし、最も高くつくものです。内部の関数シグネチャは自由にリファクタリングできます。公開されたAPIは違います。会うことのないかもしれない利用者への約束であり、それを破ることは利用者を壊すことです。組織がモノリスをサービスに分割し、パートナーや公衆に機能を開放するにつれて、APIは主な製品の表面であり、主な統合リスクになります。

大きなチームにとって、APIは人々が独立して働けるようにするものです。よく設計されたインターフェースは、あらゆる利用者と調整することなく内部を変更できるようにし、それこそがサービス境界の要点です。まずく設計されたものは、内部の詳細を漏らし、足並みを揃えたデプロイを強い、サービスの集合を分散モノリスに変えます。つまり、分割されながらも、一緒に構築しデプロイしなければならないほど結合したサービスです。API設計は、チームがどれだけ独立して動けるかを直接決めます。

企業や政府の設定では、APIにはコンプライアンス、セキュリティ、長寿命の義務も伴います。公共部門のAPIは、オープンスタンダードに従い、何年も安定を保ち、調整できない外部の開発者に仕えることが求められるかもしれません。企業のAPIは、契約上のサービスレベルを伴うパートナー統合を支えます。これらすべてが、バージョニングの規律、後方互換性、ガバナンス、開発者体験のハードルを上げます。

主要原則

まず契約を設計します。インターフェースは、実装の副産物ではなく、意図した製品の決定です。
自分の都合ではなく、利用者の体験のために最適化します。
後方互換性を約束として扱います。破壊的な変更には、新しいバージョンと移行の道筋が必要です。
簡単なことを正しいことにします。妥当な既定値、予測可能なエラー、一貫した規約。
失敗を前提に設計します。冪等性(繰り返されたリクエストが単一のリクエストと同じ効果を持つこと)、リトライ、ページネーション、レート制限は、後付けではなく第一級の関心事です。
プロトコルのスタイルは、流行ではなく、やり取りに合わせて選びます。
APIを、オーナー、ライフサイクル、ドキュメントを伴う製品として統治します。

推奨事項

APIファーストで契約駆動に取り組む

実装を書く前に、リソース、操作、スキーマ、エラーの意味論を含むAPI契約を定義し、レビューします。機械可読な仕様を使い、契約からドキュメント、クライアントとサーバーのスタブ、モックサーバー、検証を生成できるようにします。そうすれば、利用者はあなたが構築している間にモックに対して統合を始められ、契約は双方がテストする唯一の信頼できる情報源になります。

やり取りのスタイルを意図して選ぶ

REST(表現状態転送)、GraphQL、gRPC、イベント駆動メッセージングの中から、個人の好みではなく、やり取りに基づいて選びます。リソース指向で、広く相互運用でき、キャッシュ可能なインターフェースにはRESTを使います。多様なクライアントが、豊かなグラフに対する柔軟で集約された読み取りを必要とするときは、GraphQLを使います。内部サービス間の高性能で強く型付けされた呼び出しにはgRPCを使います。非同期で疎結合なワークフローと状態変化の伝播にはイベント駆動メッセージングを使います。多くの大きなシステムは、複数のスタイルを同時に使い、それぞれが合う場所に置かれます。

規律をもってバージョニングし、非推奨にする

明示的なバージョニング戦略と、公開された非推奨ポリシーを採用します。変更をどう分類するか、古いバージョンをどれだけ長くサポートするか、利用者にどう通知するか。後方互換な変更(任意フィールドの追加、新しいエンドポイント)と、破壊的な変更(フィールドの削除や改名、型や意味論の変更)の間に明確な線を引きます。既存のフィールドの意味を転用してはいけません。利用者が移行するための重複期間を与え、スケジュールを十分前に伝えます。

エラーの意味論を一貫させ、機械可読にする

構造化され予測可能なエラーを返します。安定した機械可読なコード、人間が読めるメッセージ、そして行動に移すのに十分な文脈を、機微な内部を漏らさずに。すべてのエンドポイントで同じステータスの意味論を使い、クライアントがエラーを一様に扱えるようにします。利用者が遭遇しうるすべてのエラーを文書化します。

冪等性、ページネーション、レート制限を組み込む

冪等性キーをサポートして書き込み操作を安全にリトライできるようにし、タイムアウト後にリトライするクライアントが、二重に課金したり二重に作成したりしないようにします。初日からすべての一覧エンドポイントにページネーションを設け、大きなデータセットや変化するデータセットにはカーソルベースのページネーションを好みます。レート制限を適用して文書化し、クライアントが穏やかに引き下がれるよう、現在の制限状態をクライアントに返します。

APIを統治し、開発者体験に投資する

各APIを、オーナー、ライフサイクル、カタログのエントリを持つ製品として扱います。チーム間でインターフェースが一貫するよう、設計レビューやAPI標準委員会を設けます。開発者体験に投資します。正確なリファレンスドキュメント、クイックスタート、例、サンドボックス、変更履歴。大きなエコシステムでは、APIを発見可能にするポータルやカタログが不可欠です。

トレードオフ: 長所と短所

スタイル	最適な用途	長所	短所
REST / HTTP	公開された、リソース指向のAPI	遍在的、キャッシュ可能、単純、相互運用可能	過剰/過少取得。多くのラウンドトリップ。仕様化されなければ緩い契約
GraphQL	多様なクライアントへの柔軟な読み取り	クライアントが指定するクエリ。単一のエンドポイント。強いスキーマ	キャッシュとレート制限の複雑さ。クエリコストのリスク。サーバーの複雑さ
gRPC	内部の高性能な呼び出し	高速、コンパクト、強く型付け、ストリーミング	ブラウザのサポートが弱い。人間には読みにくい。ツールが重い
イベント駆動	非同期で疎結合なワークフロー	疎結合。スケーラブル。レジリエント	推論が難しい。結果整合性。運用の複雑さ

バージョニングの戦略は、安定性と保守を天秤にかけます。多くの古いバージョンをサポートすると利用者を守れますが、保守しテストしなければならないコードが増えます。後方互換性は、自分自身の自由を利用者の安定と引き換えにし、広く使われるAPIにとっては通常、正しい取引です。全体像として、悪いAPIの決定のコストは、インターフェースの全寿命にわたって、すべての利用者が支払います。だから、境界には、ほとんど他のどこよりも多くの設計の労力を費やす価値があります。

チームで議論すべき問い

変更を後方互換か破壊的かにどう分類し、黙った破壊が出荷される前に捉える自動チェックは何ですか。 本章は厳しい線を引きます。任意フィールドと新しいエンドポイントの追加は安全で、フィールドの削除や改名、型の変更、フィールドの意味の転用は利用者を壊します。大きなチームでは、変更を加える人がすべての利用者を見られないことが多く、「小さな」調整が、話すことのないパートナーを静かに壊しえます。具体的なシグナルを会議に持ち込んでください。公開された仕様に対する契約互換性の自動チェックをCIで実行していますか。それとも誰かがルールを覚えていることに頼っていますか。破壊的な変更がすべてのパートナーにわたる調整された移行を強い、ベンダーや政権の交代にまたがりうる企業や政府の設定では、コストは利用者数に比例して増えます。分類ルールを決め、互換性のゲートを組み込み、非互換な変更が、統合ではなくビルドを失敗させるようにしてください。
どの信頼性のプリミティブ、冪等性キー、ページネーション、レート制限が、初日からすべての新しいエンドポイントで必須ですか。 本章はこれらを第一級の関心事と主張します。稼働中の課金エンドポイントに冪等性キーを後付けしたり、すでに出荷されている一覧にページネーションを加えたりすること自体が、破壊的な変更だからです。大きなエコシステムはこれを増幅します。テストでは動くエンドポイントが本物のデータ量で崩壊し、冪等でない書き込みは、一度のネットワークの瞬断を重複した課金に変えます。現在のどのエンドポイントがこれらを欠いているか、リトライの嵐が何を引き起こすかの証拠を持ち込んでください。新しいエンドポイントの既定を交渉の余地のないものにします。すべての一覧にカーソルページネーション、すべての書き込みに冪等性キー、現在の状態を返す文書化されたレート制限。これで、将来の強制的な移行を、一度きりの設計の習慣に変えられます。
実装を書く前に本当に契約を設計しレビューしていますか。それとも、インターフェースがコードから漏れ出していますか。 APIファーストの推奨は、レビューされた機械可読な仕様を前もって求め、それがドキュメント、スタブ、モックを生成し、あなたが構築している間に利用者がモックに対して統合できるようにします。契約が実装に遅れると、インターフェースは内部のデータベース構造を露出し、実装が変わるたびに変わります。これは本章の最上位のアンチパターンです。調べるべきシグナルは、利用者が今日あなたのモックに対して統合を始められるか、それとも稼働するバックエンドを待たなければならないかです。インターフェースが製品の表面であり、間違えると最も高くつく公開APIとパートナーAPIでは、契約に一日を費やすことが、何週間ものサポートの往復を省きます。実装が始まる前に、契約レビューを必須のステップにしてください。
二つのチームが同じ機能を公開する必要があるとき、どのやり取りのスタイルが勝ち、四つ目のプロトコルにノーと言う権限は誰にありますか。 本章は、REST、GraphQL、gRPC、イベント駆動メッセージングを、やり取りへの適合性で選ぶよう言いますが、規模が大きくなると本当のリスクは、すべてのチームが自分の好みを選び、利用者があらゆるエンドポイントで異なる規約に直面することです。大きな組織は、その分断を、クライアントライブラリ、ゲートウェイ、モニタリング、そして一つではなく四つのイディオムを学ぶことになったすべての統合担当者の認知負荷で支払います。すでに本番にあるプロトコルの一覧と、それぞれがどのやり取りのために選ばれたか、複数にまたがる利用者を持ち込んでください。相反する考慮は本物です。共有の既定は乱立を減らしますが、硬直した義務づけは、gRPC型の問題をREST型の穴に押し込みます。例外のプロセスを所有する標準化の組織やアーキテクチャレビューに名前を付けてください。企業や政府の資産では、スタイルの増殖が統合への恒久的な税になり、パートナーがそれぞれに依存するようになると、元に戻すのが難しい問題になるからです。
私たちの公開された非推奨ポリシーは何で、宣伝しているサポート期間を実際に守っていることを証明できますか。 本章は、バージョニングと非推奨を規律として扱います。古いバージョンがどれだけ長く生きるか、利用者にどう通知するか、移行のためにどんな重複期間を与えるかについての書面のポリシー。強制できない約束は、ないよりも悪いものです。大きなエコシステムには、話すことのない利用者が含まれ、本番で壊れるまで退役したバージョンを呼び続けるからです。議論に証拠を持ち込んでください。今日抱えているライブのバージョンの数、それぞれの実際の利用状況、非推奨のエンドポイントを今も呼んでいる利用者が見えるか、直近のサンセットがどれだけ前に告知されたか。相反する圧力は、保守コストと利用者の安定であり、どちらも本物です。契約上のサービスレベルのもとにある企業のパートナーや、政権とベンダーの交代を越えて生き延びなければならない公共部門のAPIでは、サポート期間は、それを約束したチームより長く続きうるコミットメントなので、誰がそれを所有し、サンセットが事前に安全だとどう証明するかを決めてください。
私たちの開発者体験が良いことを、どうやって知りますか。それとも、APIが自分たちには動くからと想定していませんか。 本章は各APIを、その採用が、正確なリファレンスドキュメント、クイックスタート、例、サンドボックス、変更履歴、発見可能なカタログに依存する製品として枠づけています。チームは日常的に「APIが機能する」を「APIが使える」と取り違え、そのギャップは、サポートチケット、失敗した統合、静かに諦める利用者として現れます。意見ではなく測定可能なシグナルを持ち込んでください。新しい統合担当者の最初の成功した呼び出しまでの時間、エンドポイントごとのサポートチケット数、公開ドキュメントが稼働中の契約に対してどれだけ古いか、新参者がチームにメールせずにポータルから自力で進められるか。緊張は、ドキュメントとポータルが、機能の出荷と競合する本物の労力を要することですが、大きなエコシステムでは、貧しい開発者体験は、統合コストを何百もの利用者に一度に押しつけます。調整できない外部の開発者に開かれたAPIが仕え、透明性がしばしば義務づけられる政府では、使いやすく、よく文書化され、発見可能なインターフェースは、あれば嬉しいものではなく、公共の説明責任の義務の一部です。

セクター別の視点

スタートアップ。 2、3人のエンジニアで儀式の時間もないので、契約を軽く、しかし本物に保ってください。最初のデザインパートナーの顧客が、あなたが構築している間に統合できる、機械可読な仕様を一つ。APIゲートウェイ、カタログ、ガバナンス委員会はまだ立ち上げませんが、後から加えるのが苦痛な二つの習慣、書き込みの冪等性キーと一覧のカーソルページネーションは確保してください。稼働中のエンドポイントに後付けすることは、あなたに負えない破壊的な変更だからです。やり取りのスタイルは一つ、ほぼ常にRESTを好み、最初の一年にプロトコルの乱立を持ち込まないようにします。

小規模事業者。 専任のAPIの専門家はおらず予算も厳しいので、仕様からドキュメント、モック、クライアントのスタブを生成するツールに頼り、ゼネラリストが深いプロトコルの専門性なしにインターフェースを保守できるようにします。買うか作るかを真剣に比べてください。既製のゲートウェイやAPI管理プラットフォームは、そうでなければ手作りするレート制限、キー、開発者ポータルを提供します。表面を小さく、規約を一貫させてください。余分なエンドポイントや一回限りのエラー形式は、少人数のチームが永遠にサポートしなければならないものだからです。

大企業。 多くの自律的なチームにわたって、中心的な問題は、ボトルネックにならずに一貫性を保つことです。共有のスタイルガイド、API標準のレビュー、インターフェースを発見可能にするカタログ、そして黙った破壊が統合ではなくビルドを失敗させるよう、CIでの自動の後方互換性チェック。各APIを、名前のあるオーナー、ライフサイクル、公開された非推奨ポリシーを持つ製品として統治し、採用、サポート負荷、破壊的変更の頻度を測定して、ポートフォリオを健全に保ちます。この規模では分断が高価な既定なので、やり取りのスタイルとバージョニングのルールを、組織全体で標準化してください。

政府。 調達規則、オープンスタンダードの義務づけ、公的な説明責任が、あらゆる選択を形づくります。契約をオープンに公開し、義務づけられたオープンスタンダードに従い、調整できない外部の開発者が自力で進められるよう、サンドボックスとリファレンスドキュメントを提供します。統合が政権とベンダーの交代を越えて生き延びなければならないので、長期の後方互換性を政策上の要件として扱い、破壊的な変更を、まれで、厳しく統治され、ずっと前に告知されるものにします。APIとそのドキュメントを、公衆と監査の精査に耐えるほど透明に保ち、将来の政権を閉じ込める独自の形式を避けます。

事例

スタートアップ。 最初の公開APIを出荷するシード段階のスタートアップは、コーディングの前に機械可読な仕様として契約を書くので、二つのデザインパートナーの顧客は、バックエンドがまだ構築中の間にモックに対して統合できます。利用者がほんの数人でも、課金エンドポイントに冪等性キーを、すべての一覧にカーソルページネーションを加えます。パートナーがAPIに依存してから後付けすれば、負えない破壊的な変更になるからです。前もっての契約は一日かかり、何週間ものサポートの往復を省きます。

大企業。 大手の決済会社が、数千の加盟店に公開のREST APIを提供しています。すべての書き込みエンドポイントは冪等性キーを受け付けるので、ネットワークのリトライが重複した課金を作ることはありません。すべての一覧エンドポイントはカーソルページネーションを使います。エラーは、公開リファレンスに文書化された安定したコードを伴います。正式な非推奨ポリシーが、どのバージョンにも長いサポート期間を、事前の通知と移行ガイドとともに保証します。この規律は競争上の強みです。統合担当者は、APIが自分たちの下で壊れないと信頼しています。

政府。 国のデジタルサービスが、義務づけられたオープンスタンダードとAPIファーストの設計プロセスに従って、市民データのオープンなAPIを公開しています。契約は構築の前に規定されレビューされ、政府の中央のAPIカタログで公開され、サンドボックスとともに提供されるので、個別に調整できないサードパーティの開発者が、自力で統合できます。統合が政権とベンダーの交代を越えて生き延びなければならないため、長期の後方互換性は政策上の要件です。そのため、破壊的な変更はまれで、厳しく統治されています。

ビジネスケース: 動機、ROI、TCO

良いAPI設計は統合コストを下げます。それはしばしば、システムの接続とパートナーのオンボーディングにおける最大のコストです。明確で安定した、よく文書化されたAPIがあれば、利用者はサポートチケットを一件も出さずに数日で統合します。まずいものは、終わりのないサポート負荷、失敗した統合、評判の傷を生みます。APIそのものが製品であるとき、開発者体験は採用と収益を直接動かします。

最大の隠れたコストは破壊的な変更です。あらゆる破壊的な変更は、内部のチームも外部のパートナーも含め、すべての利用者にわたる調整された移行を強い、総コストは、利用者の数と、足並みを揃えて移行することの難しさに比例して増えます。契約優先の設計、後方互換性、バージョニングの規律への前もっての投資は、これらの高価で組織全体にわたる移行のイベントを避けます。リーダーシップに話すときは、API品質を、チームの自律、パートナーのエコシステムの成長、高価な強制移行の回避のための、てこの点として枠づけてください。統合の時間、サポートチケット数、破壊的変更の頻度を、証拠として追跡します。

アンチパターンと落とし穴

実装ファーストのAPI: インターフェースが内部のデータベース構造を漏らし、実装が変わるたびに変わること。
黙った破壊的変更: バージョンを上げずにフィールドを転用したり検証を厳しくしたりして、利用者を予測不能に壊すこと。
おしゃべりなインターフェース: 一つの論理操作に多くのラウンドトリップを要する設計で、性能と使いやすさを損ないます。
一貫しない規約: すべてのエンドポイントが独自の命名、エラー形式、ページネーションを発明し、クライアントが一般化できないこと。
ページネーションもレート制限もない: テストでは動くが、本物のデータ量や負荷で崩壊するエンドポイント。
冪等でない書き込み: リトライが重複を引き起こし、一度のネットワークの瞬断がデータを壊すこと。
バージョンの増殖: 非推奨にならない生きたバージョンが多すぎて、手に負えなくなるまで保守が増えること。
後回しのドキュメント: ドキュメントがない、あるいは古いリファレンスが、統合のコストをすべて利用者に押しつけること。

成熟度モデル

レベル1、開始: APIは副産物として実装から現れ、共有の規約はなく、インターフェースは内部のデータベース構造を漏らし、破壊的な変更は一般的で、告知されず、利用者の統合が失敗したときに発見されます。
レベル2、発展: 一部のチームは基本的なREST規約に従い、非公式にバージョン管理し、手書きでドキュメントを書きますが、実践はチーム間で一貫しません。冪等性、ページネーション、レート制限は一部のエンドポイントにあって他にはなく、利用者は各APIの癖をケースごとに学び続けます。
レベル3、標準化: 機械可読な仕様による契約優先の設計が文書化され、組織全体で徹底されています。公開された非推奨ポリシー、一貫したエラーの意味論、そして必須の冪等性、カーソルページネーション、レート制限が、すべての新しいエンドポイントに適用され、共有のスタイルガイドとAPI標準のレビューが、チーム間でインターフェースを一貫させます。
レベル4、管理: APIポートフォリオは、ベースラインに対して測定され、制御されます。自動の後方互換性チェックがCIですべての変更をゲートし、最初の成功した呼び出しまでの時間、エンドポイントごとのサポートチケット数、破壊的変更の頻度、ライブのバージョン数、エンドポイントごとの利用状況が追跡され、非推奨と設計の判断が意見ではなく証拠に基づきます。各APIは、名前のあるオーナーを持つ、カタログ内の統治された製品で、サービスが目標からずれたときは指標が行動を引き起こします。
レベル5、オーケストレーション: API戦略は継続的に改善され、組織全体に統合されています。カタログ、ゲートウェイ、バージョニングのルール、互換性のゲートが一つのシステムとして働き、組織は測定された採用とコストに基づいて、インターフェースを日常的に退役、統合、スコープ見直しし、やり取りのスタイルとバージョニングの標準は、エコシステム、パートナー、技術の変化に応じて適応し、破壊的な変更はまれでよく管理されています。

議論のためのアイデア

内部APIが外部に公開するのに十分安定していると、どう判断しますか。
あなたの文脈で、非推奨バージョンの適切なサポート期間は何で、誰が負担しますか。
社内でGraphQLやgRPCがRESTに取って代わるべきなのはどこで、価値より複雑さを加えるのはどこですか。
ボトルネックにならずに、多くの自律的なチームにわたってAPIの一貫性をどう徹底しますか。
AIが利用するAPIやエージェントのツールインターフェースは、設計の規約をどう変えるべきですか。
後方互換でない変更を、出荷前に捉えられる自動チェックには何がありますか。

要点

まず契約を設計します。APIは製品であり、長寿命の約束です。
後方互換性は利用者を守ります。破壊的な変更には、新しいバージョンと移行の道筋が必要です。
REST、GraphQL、gRPC、イベントは、流行ではなくやり取りへの適合性で選びます。
冪等性、ページネーション、レート制限、一貫したエラーを初日から組み込みます。
APIを、オーナー、カタログ、優れた開発者体験を伴う製品として統治します。

参考文献とさらなる読み物

Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures (dissertation)
Arnaud Lauret, The Design of Web APIs
Mike Amundsen, RESTful Web APIs and Design and Build Great Web APIs
Sam Newman, Building Microservices
OpenAPI Specification; JSON Schema (as reference standards)
Martin Kleppmann, Designing Data-Intensive Applications