api-integration-surface-strategy

API インテグレーションサーフェス戦略

プラットフォームチームのインテグレーションサーフェス戦略担当として、REST、Webhooks、GraphQL、gRPC、SQL アクセス、一括データ共有、SDK、CLI、MCP、埋め込みコンポーネントなど、プラットフォームが外部の開発者や AI エージェントにどのサーフェスを提供するか、またどの順番で構築するかを決定します。各サーフェスについて、対象者と需要のシグナルを明記した、順序付きの計画を一つ作成してください。

これは、このコレクションにある各サーフェス別のスキルに先立つ、包括的な判断です。各サーフェスの設計は個別のスキルが担当します（「参考資料」を参照）。このスキルでは、サーフェスをいつ、どのような場合に選択肢に加えるかを判断してから、担当に引き継ぎます。全体を通じた基本原則は、新しさではなく、変更時のコストと対象者です。REST の追加的な変更は簡単に元に戻せますが、すでに依存する利用者がいる公開契約は、変更がほぼ不可能です。

Hyrum の法則は、その仕組みを示しています。「API のユーザーが十分な数に達すると、システムの観察可能な振る舞いはすべて、誰かに依存されるようになる」。成熟したプラットフォームが、基盤となるレイヤーの安定を待ってから、より抽象度の高いサーフェスの採用を決めるのはこのためです。

メモリ（推奨）：メモリをファイルに保存する場合は、developer-platform-context.md の使用を検討してください。別のメモリシステムを使用している場合は、そちらを利用してください。このファイルは参考資料であり、必須ではありません。タスク情報はセクションを分けて記載してください。完了したタスクは削除してください。タスクには日付を付け、一般的なプロジェクトのコンテキストには日付を付けないでください。インタビューの回答は、タスクによって異なる場合があります。

インタビュー

1 回のメッセージで質問を 1 つ尋ね、回答を待ってください。それぞれの回答が後の手順に影響します。選択肢が提示されている場合は、複数選択肢を提示してください。

1. 誰が製品を選びますか。購入者のタイプはどれですか。（a）開発者がボトムアップでツールを選ぶ、（b）技術職ではないビジネス上の購入者が選ぶ、（c）同じ商談で両者が関わる（経済的な購入者に加え、技術ユーザーが製品を評価する）。これは、何よりも API ファーストか、埋め込みファーストかという方針に影響します。
2. 現在、どのサーフェスがどの程度提供されていますか。それぞれについて、完全にセルフサービスで利用可能、一部対応（API はあるものの、一部の手順はまだ手動）、未提供のいずれかを確認してください。機能ごとの対応範囲も詳しく尋ねてください。一部しか API で利用できないフローでは、パートナーが期待していたインテグレーションが機能しません。
3. 機械可読な仕様（OpenAPI または同等のもの）はどのような状態ですか。（a）CI でリントされる信頼できる情報源、（b）存在するが API との乖離がある、（c）なし。SDK、MCP、生成ドキュメントなど、そこから派生するすべてのサーフェスがこの回答に依存します。
4. 実際に確認できる需要のシグナルは何ですか。（a）商談を妨げている未提供のサーフェスを示すパイプライン／営業データ、（b）クライアント種別ごとの利用状況テレメトリー（例：SDK／ライブラリのユーザーエージェントの割合）、（c）コミュニティからの要望や開発者エンゲージメントのシグナル、（d）まだ何も計測していない。
5. AI エージェントからの需要はすでにありますか。（a）MCP との互換性を求める RFP またはセキュリティレビュー、（b）既存サーフェスで確認されたエージェントのトラフィック、（c）顧客からの質問のみ、（d）なし。
6. チームが継続的に維持できるサーフェスの数はどのくらいですか。何年にもわたって構築、文書化、サポートし、リリースを続けられる数を答えてください。意気込みではなく、具体的な数を挙げてください。
7. 最初の新しいサーフェスをいつまでに提供する必要がありますか。ローンチ、商談、または RFP の期限によって順番が決まっていますか。
8. これは、一度限りの障害解消（商談で必要なサーフェスをリリースする）ですか。それとも、長期的な資産（チームが何年も取り組むサーフェスのロードマップ）ですか。
9. 労力の上限はどのくらいですか。確保できるエンジニアの作業時間、サーフェスごとに継続的なメンテナンスを行う意欲、各選択をどの程度元に戻せる必要があるかを確認してください。

回答 7〜9 によって、ステップ 4 での選択肢の順位が変わります。厳しい期限がある場合は、すぐに追加できるサーフェスの順位が上がります。長期的に積み上がる資産を目指す場合は、その後のすべてのサーフェスの基盤となる仕様の整備が優先されます。

購入者の種類ごとに分けた対象ユーザー

戦略を変える情報源に基づく分類は、購入者の種類です。つまり、開発者がツールを選ぶのか、それとも技術職ではない購入者が選ぶのかです。

• Stripe：APIを開発者に販売して成功しました（「7行のコード」、ダッシュボードはその後）。
• PayPal：事業主にチェックアウトボタンを販売しました。同じ業界でも、提示する順序は正反対です。

何かを順位付けする前に、インタビュー回答1をreferences/surface-condition-tables.mdの条件表に当てはめてください。APIファーストと埋め込み型ファーストは、競合する選択肢ではなく、層として扱ってください。

記録されているパターンでは、APIファーストを持続可能な基盤とし、取引における技術職ではない側のために、埋め込み型／ノーコードの層をその上に追加します。Stripe自身も両方を実現しました。技術ユーザーだけ、または経済的な購入者だけに届くサーフェスを選んでも、取引は停滞します。

候補となる順序付け計画のブレインストーミング

計画を書く前に、トレードオフと推奨案を添えて、候補となる順序を2～3案提示し、ユーザーに選択または組み合わせてもらってください。候補はステップ4の方針を基に作成します。

• 仕様ファーストで導出する順序。
• 技術職ではない購入者向けに、埋め込み型を先行させる順序。
• 営業が挙げた1つのサーフェスを先行させる、取引主導型の順序。

次に、計画の各セクションを順番に（以下のワークフローの各ステップにつき1つ）作成し、次へ進む前にユーザーの承認を得てください。すべてのセクションが承認されるまで、最終版にしないでください。

ハーネスに永続メモリがある場合は、承認された決定事項を記録してください。後続のサーフェスごとの実行時に、再度インタビューせずにそれらを読み込めるようにします。

• サーフェスの一覧と順序。
• サーフェスごとの対象ユーザーと需要シグナル。
• 容量の上限。
• レビュー日。

ワークフロー

1. 対象ユーザーと購入者をマッピングします。
2. 現在のサーフェスと仕様を棚卸しします。
3. 需要シグナルを確認します。
4. サーフェスの順位付けと順序付けを行います。
5. サーフェスごとの引き継ぎ内容を作成します。
6. レビューの頻度を設定します。

各ステップには、以下に記載された順番どおりにセクションがあります。すべてのステップで、計画のセクションを文書化してください。会話だけで終わったステップは完了ではありません。

1. 対象ユーザーと購入者をマッピングする

プラットフォームがサービスを提供している、または提供を目指しているすべての利用者層を列挙します。

• 自社の開発者。
• サードパーティのインテグレーター。
• 技術職ではないオペレーター。
• BI／分析の利用者。
• AI エージェント。

各利用者について、呼び出しコードを書くのが誰か（人、ジェネレーター、エージェント）と、インタビュー回答1におけるどの購入者に該当するかを記録します。

異なるサーフェスは、互いに置き換わるのではなく、異なる利用者に対応する形で存続します。

• RESTとGraphQLは、人が書くソフトウェアに対応します。
• SQLと一括処理用ファイルは、BI利用者に対応します。
• MCPは、エージェントのクライアントに対応します。

計画は利用者ごとのマップであり、すべての利用者がたどる単一の段階ではありません。

2. 現在のサーフェスと仕様を棚卸しする

既存の各サーフェスを表にまとめ、次の項目を列に含めます。

• 対応する対象ユーザー。
• 対応範囲（最初から最後までセルフサービス可能、または一部のみ）。
• 仕様から生成されるか、手作業で構築されているか。
• テレメトリーがある場合は、観測されたトラフィックの割合。

対応が不十分な範囲は明示的に示します。インテークはカバーしているものの、その後のステップを手作業のままにするAPIは、チェック済みの項目ではなく、明確に認識された失敗パターンです。

仕様の状態（インタビュー回答3）を、計画の中心的な依存関係として記録します。Stripe、Twilio、Cloudflareでは、SDK、MCPツール、リファレンスドキュメントがすべて単一のOpenAPIを信頼できる唯一の情報源として生成されるため、サーフェスごとに移行する必要がなく、1つの変更がすべてに反映されます。仕様にずれがある場合は、そこから派生するサーフェスを予定に入れる前に修正します。

3. 需要のシグナルを読み解く

シグナルの重みを比較します。単に集めるだけではありません。

• パイプライン／営業データの重みが最も高い - 頻度は低くても深刻度は高いシグナルです。対応していないサーフェスに直面したアカウントは解約したり、商談が停滞したりします。具体的な商談の阻害要因は、どのような量の指標よりも優先されます。
• サーフェスとクライアント種別ごとの使用状況テレメトリは、量に関する最も強いシグナルです。Twilio が SDK に投資した理由は、まさにこれでした。REST API リクエストの 77% にヘルパーライブラリの user-agent が含まれていたため、ライブラリを正式に整備し、その後自動生成することが正当化されました。
• コミュニティとエンゲージメントのシグナル（要望、スター、フォーラムでの話題）は 3 番目に位置します。実態を反映していますが、簡単に発生させられ、過大評価しやすいシグナルです。
• AI エージェントの需要（インタビュー回答 5）が MCP の導入時期を決めます。MCP 互換性を求める RFP が出始めれば優先度が上がります。エージェント関連のシグナルがなければ、ブームの状況にかかわらず、後回しのままです。

回答 4 が「計測していない」であれば、クライアントごとのテレメトリ計測を早期の計画項目にしてください。後で優先順位を再評価する際に、そのデータが必要になります。

4. サーフェスの優先順位を決め、順序を定める

個々のサーフェスを並べる前に、どのサーフェス群を軸に順序を組み立てるか、リードする方針の順位を決めます。

• 労力（継続的に必要となる作業量）：GraphQL-led > embedded-first > REST+webhooks-first

• 方針を覆すコスト（誤った決定をやり直すためのコスト）：GraphQL-led > embedded-first > REST+webhooks-first

• 価値（同じ契約から実現できる下流のサーフェス）：REST+webhooks-first > GraphQL-led > embedded-first

• 効率：REST+webhooks-first > embedded-first > GraphQL-led

• デフォルトの段階：RESTとWebhooksを最初に。 RESTはほぼ普遍的な基盤（GraphQLの採用率が33％であるのに対し、RESTは93％。Postman 2025）であり、加算的に拡張できます。新しいエンドポイントや任意のパラメーターを追加しても安全なため、初期の判断ミスによるコストを低く抑えられます。Webhooksも新しいパラダイムを導入するのではなく、同じインフラを活用します。その後のすべてはこの契約から派生します。

• 組み込み優先 - ホワイトラベルのコンポーネントや組み込みiPaaSレイヤーが先導する場合です。インタビューの回答1から、購入者が技術者ではなく、価値実現までの日数ではなく時間が求められると分かった場合は、条件表に従ってこれを優先します。柔軟性を犠牲にする代わりに、連携が「そのまま動く」状態を実現します。それでも、基盤となるAPIは計画してください。後から導入する方がコストのかかる方向です。

• 後回しにされる選択肢：GraphQL-led。 クライアント主導のデータアクセス、モバイルでの過剰取得や取得不足、またはN+1問題が実際にある場合、クライアントごとの価値は最も高くなります。一方で、継続的な労力も大きく（チームの報告では初期構築におよそ20～40％のオーバーヘッドがかかり、さらにN+1問題や認可の複雑さも伴います）、スキーマは厳格で拘束力のある公開契約となります。効率の比較では、すべての段階で劣ります。それでも、連携担当者が確認した、明確に特定された課題があれば、優先する理由になります。ShopifyはAdmin APIでGraphQLファーストを採用し、冗長さをめぐって開発者から大きな反発を受けました。これは、どちらの方向性を論じる際にも引用してください。

MCPファーストとSDKファーストは、単に優先順位を下げるだけでなく、そもそもこの選択肢には含まれません。どちらも、すでに存在し、安定している契約から派生するものです。代わりに、計画の中で順序を定めます。SDKは契約が安定してから生成し、MCPは最後に薄い派生レイヤーとして追加します。そのタイミングはステップ3で得たエージェントのシグナルによって決まります。MCPを提供した主要プラットフォーム（2025年2月のStripe、2025年5月のCloudflare各社、2026年5月のGAにおけるAWS）はいずれも、別製品を手作業で構築するのではなく、既存のAPI上にMCPを生成しました。

この順位付けはデフォルトであり、絶対的なルールではありません。状況と実行するチームによって変わります。インタビューの回答に照らして順位を見直してください。

• 条件表に従い、回答1によって上位2つの段階が入れ替わります。
• すでに社内でGraphQLを運用しているチームなら、後回しにされる選択肢をより低コストで実現できます。
• 取引の期限（回答7）によって、特定のサーフェス1つが全体の順序より先に来ることがあります。

次に、選んだ方針の中で、サーフェスを一度に1つずつ順番に進めます。回答6で示された対応可能数を超えて、複数を並行して進めてはいけません。一度に多くを着手すると、いずれも測定が不十分なサーフェスが複数生まれ、どれについても明確なシグナルが得られません。

Twilioは、ツールによって持続可能なサポートが可能になってから、SDKの言語を追加しました。適切に仕上げた2つのサーフェスは、粗雑に仕上げた6つのサーフェスに勝ります。

サーフェスごとの方針を覆すコストの段階、購入者タイプの条件表、MCPの構築と購入のしきい値については、references/surface-condition-tables.mdを参照してください。デフォルトの順序の根拠となったSegment、Twilio、Stripe、Plaidの順序については、references/build-order-case-studies.mdを参照してください。

5. サーフェスごとの引き継ぎ事項を記録する

計画で予定している各サーフェスについて、次の項目を記録します。

• 対象ユーザー。
• そのサーフェスを正当化した需要シグナル。
• 逆転コストのティア。
• キャパシティの責任者。
• 設計を担当する兄弟スキル（「参考資料」を参照）。

役割分担は固定です。

• このスキルは、何を、_いつ_行うかを決定します。
• 兄弟スキルは、_どのように_行うかを決定します。

gRPC サーフェスの設計は samber/developer-platform-skills@public-grpc-api-design が担当します。バルクデータ／レイクサーフェスの設計は、需要シグナルが示す形態に応じて、samber/developer-platform-skills@bulk-data-sharing-design（ファイル／レイクエクスポート）または @etl-connector-strategy（ELT ツールを通じて同期する行データ）が担当します。

埋め込みコンポーネントには専用の兄弟スキルがありません。設計上の決定事項は計画自体に記録します。CLI の設計は samber/developer-platform-skills@cli-interface-design が担当します。ここでは、対象ユーザーと、二者向けの価値提案（Plaid の 2025 年のパターンである、人には読みやすいテーブルを、エージェントには stdout と stderr を明確に分離した JSON を提供すること）のみを記録します。

CLI、SDK、ライブラリとともに提供する、特定のテクノロジー向けエージェントスキルは samber/developer-platform-skills@agent-skill-offering が担当します。これにより、コードとともにバージョン管理されます。

エージェントが明示的な対象ユーザーになった場合、エージェントクラス計画（どのエージェントがどのサーフェスに到達し、どのように認証してユーザーに代わって動作し、登録し、利用状況を計測するか）は samber/developer-platform-skills@agent-integration-surfaces が担当します。ここでは、MCP と CLI をビルド順のどの段階で組み込むかのみを記録します。

プラットフォームの長期的な構成オブジェクトを扱う Terraform/OpenTofu プロバイダーは samber/developer-platform-skills@terraform-provider-offering が担当します。SDK と同様に REST コントラクトから派生するため、そのコントラクトが安定してから予定に組み込みます。ここでは、対象ユーザー（プラットフォームチームとインフラストラクチャチーム）と需要シグナルのみを記録します。

6. レビューの頻度を設定する

シグナルの変化に伴い、サーフェス計画は古くなります。レビュー日（四半期ごとが妥当な初期設定です）と、計画を早期に見直すきっかけを設定します。

• 欠けているサーフェスが原因で商談が停滞している。
• エージェント需要のシグナルが現れる（質問 5 の回答が「なし」から「RFP」に変わる）。
• テレメトリが対象ユーザーのマップと矛盾している。
• 予定されているサーフェスの担当者がキャパシティを失う。

計画全体を再び議論するのではなく、次回のレビューで再確認すべき根拠を記録します。

失敗パターン

• 新しさを理由に MCP から始める。 新しいという理由で最新のサーフェスから構築すると、フレームワーク全体が逆転します。構築順は逆転コストと対象ユーザーによって決まり、MCP はラップする API があることを前提とします。ステップ 3 のエージェントシグナルが変化するまで、導入を保留します。
• MCP サーフェスを手作業で構築する。 名前の挙がったプラットフォームはすべて、既存の仕様から MCP サーバーを生成しています。手作業で構築すると数週間の作業に加えて継続的なメンテナンスが必要になり、ジェネレーターで生成できるものを作り直すことになります。自社の独自システムへの AI アクセスそのものが有料製品である場合に限り、社内で構築します。
• エージェントの呼び出しごとの課金を収益源と見込む。 決済基盤は存在します（Stripe の MPP、x402 プロトコル）が、ユニットエコノミクスは実証されていません。観測された呼び出しごとの利用量はごくわずかで、一部はウォッシュトレードです。計画に記載する MCP の収益化案には、推測段階であることを明記します。
• テレメトリなしでサーフェスを増やしすぎる。 直感に頼って一度に複数のサーフェスを追加すると、どれからも明確なシグナルが得られず、すべてに継続的なメンテナンス費用がかかります。一度に一つずつ、キャパシティに見合った順序で追加し、まずテレメトリを計測できるようにします。
• API ファーストを表面的に捉える。 各フローの一部しか API 経由で実行できないのに API ファーストを掲げると、パートナーは統合の途中で、後続の手順には手作業が必要だと気づきます。ステップ 2 の深度調査は、パートナーが気づく前にこれを検出するためのものです。
• API ファーストと埋め込みを競合する選択肢として扱う。 どちらか一方を永続的に選ぶと、商談の片側に過剰に対応することになります。記録されたパターンは、API を基盤とし、その上に埋め込みを加速要素として重ねるレイヤー構造です。

測定

• 計画のカバレッジゲート：計画内のすべての提供形態（予定、延期、見送りを問わず）に、引き継ぎに必要な5つのフィールド（対象者、需要シグナル、変更コストの区分、担当者、担当する関連項目またはインラインでの判断）がすべて含まれている必要があります。100％でなければ計画は未完成です。合格するまで見直してください。
• 派生関係のゲート：派生する提供形態（SDK、MCP、生成ドキュメント、API上に組み込まれたレイヤー）を、その基盤となる契約がステップ2で安定版と宣言される前に予定してはなりません。二者択一です。
• 並行開発のゲート：新しい提供形態の並行開発数が、インタビューの質問6への回答で示されたキャパシティ数を超えることはありません。
• 導入後に注視する傾向（合格基準ではありません）：クライアントの種類別の提供形態ごとのトラフィック比率、商談の阻害要因ログが空になるか再び埋まるか、計画を早期に見直すべきエージェントシグナルの変化。

呼び出し例

• 「REST APIしかありません。顧客からWebhook、SDK、『MCP サポート』を求められています。何をどの順番で構築すべきでしょうか？」
• 「CEOは、当社をAIネイティブにして今四半期にMCP サーバーをリリースしたいと考えています。それをロードマップの最優先事項にすべきでしょうか？」
• 「当社の顧客は開発者ではなく、運用管理者です。それでも、購入者が求める組み込み型インテグレーションより先に、公開APIが必要でしょうか？」
• 「営業によると、倉庫データへのアクセスがないため、2件の商談を失いました。大量のデータ共有は、提供形態のロードマップのどこに位置づけるべきでしょうか？」

参考資料

• references/surface-condition-tables.md - 提供形態ごとの変更コスト区分、API優先型と組み込み優先型を判断する購入者タイプ別条件表、需要シグナルの重み付け、MCPの内製と購入の判断基準、収益化に関する注意事項。
• references/build-order-case-studies.md - 提供形態の展開スケジュールの記録：SegmentとTwilio（フィンテック以外の主要事例）、StripeとPlaid（フィンテック）、日付付きのMCPプラットフォーム公開の波。
• samber/developer-platform-skills@public-api-design-review - REST提供形態全体の契約整合性レビュー。
• samber/developer-platform-skills@webhook-platform-design - Webhook提供形態における配信、署名、再試行、サブスクリプションのライフサイクル。
• samber/developer-platform-skills@sdk-portfolio-strategy - ここでSDKを提供形態として選んだ場合のSDK言語と構築モデルの選定。
• samber/developer-platform-skills@public-graphql-api-design - GraphQL提供形態のスキーマ、ページネーション、セキュリティ設計。
• samber/developer-platform-skills@sql-jdbc-access-design - SQL/JDBC提供形態におけるテナント分離と、BI利用者向けのスキーマ安定性。
• samber/developer-platform-skills@mcp-server-offering - エージェントのシグナルを受けてここで予定した後の、MCP提供形態そのものの構築。