api-integration-surface-strategy

{
  "skill_name": "api-integration-surface-strategy",
  "evals": [
    {
      "id": 1,
      "prompt": "I'm head of platform at Veltrix, a B2B inventory-management SaaS with about 400 customers. Our CEO came back from a conference convinced we need to ship an MCP server this quarter so we're 'AI-native', and he's floated charging AI agents per API call as a new revenue line. Current state: a REST API that covers maybe 60% of product functionality, an OpenAPI file someone wrote a year ago that no longer matches the live API, and no webhooks. Our logs show zero agent traffic and no customer has ever asked about MCP. I have two backend engineers. Draft our integration-surface plan for the next two quarters.",
      "expected_output": "A sequenced surface plan that parks MCP for lack of agent-demand signals, fixes the drifting spec and shallow REST coverage first, schedules webhooks on the same foundation, labels per-call agent monetization speculative, and matches concurrency to the two-engineer capacity.",
      "files": [],
      "expectations": [
        "Recommends against building the MCP server this quarter, parking it until agent-demand signals (RFPs requiring MCP compatibility, or observed agent traffic) appear",
        "Names the absence of agent signals (zero agent traffic, no customer asks) as the reason MCP is parked, rather than arguing only from team effort or generic prioritization",
        "Identifies fixing the drifting OpenAPI spec as a prerequisite scheduled before any derived surface (SDKs, MCP, generated docs) enters the plan",
        "States that when MCP is eventually built it must be derived or generated from the existing API contract, never hand-built as a separate product",
        "Flags the 60% API coverage as a shallow-API-first failure: partners discover mid-integration that later steps still need manual touches, so depth is probed per capability",
        "Sequences REST completion plus webhooks as the first surfaces, noting webhooks ride the same infrastructure rather than opening a new paradigm",
        "Labels the per-call agent monetization idea speculative, noting unproven unit economics and that observed per-call volumes are tiny and partly wash-traded",
        "Caps concurrent new-surface builds at the stated two-engineer capacity, sequencing surfaces one at a time",
        "Includes review triggers that reopen the plan early, among them agent-demand signals moving from none to present",
        "Justifies delaying higher-abstraction surfaces via the dependency mechanism (Hyrum's Law or equivalent: once enough consumers depend on observable behavior, the contract is near-impossible to change)",
        "Establishes the buyer type (developer-chosen vs non-technical buyer) via a question or an explicit audience map before or while ranking surfaces",
        "Each scheduled surface carries a named audience and the demand signal justifying it, plus a reversal-cost tier and an owner"
      ]
    },
    {
      "id": 2,
      "prompt": "I run platform engineering at Corvana, a logistics SaaS. Our new mobile team lead insists we replace our public REST API with GraphQL - he says REST is legacy, every modern platform is moving to GraphQL, and our own mobile app genuinely over-fetches on the shipment-list screen. External integrators haven't complained about anything. We have 6 platform engineers, no internal GraphQL experience, and a stable OpenAPI-driven REST API with webhooks already live. Should GraphQL be next on our surface roadmap, and what would committing to it actually mean?",
      "expected_output": "A recommendation declining a public GraphQL surface now because the pain is first-party rather than integrator-confirmed, carrying the overhead and reversal-cost figures, the Shopify precedent in both directions, and the condition that would promote GraphQL later.",
      "files": [],
      "expectations": [
        "Declines to schedule a public GraphQL surface now because the over-fetching pain is first-party mobile, not confirmed by external integrators",
        "States that GraphQL is promoted only on named, integrator-confirmed pain (client-driven data access, over/under-fetching, N+1), never as a default REST replacement",
        "Carries the roughly 20-40% initial-build overhead plus N+1 and authorization complexity as GraphQL's standing cost",
        "Classifies a public GraphQL schema as a high reversal-cost, tight and binding contract, in contrast with additive REST changes being cheap to unwind",
        "Rebuts the 'REST is legacy' claim with REST's dominant adoption (on the order of 93% vs 33% for GraphQL, or equivalent framing of REST as the near-universal substrate)",
        "Cites Shopify's GraphQL-first Admin API in both directions: evidence a major platform anchored on it, and evidence of significant developer pushback over verbosity",
        "Notes that surfaces persist for different consumers rather than replacing one another, so GraphQL would not retire the REST contract integrators depend on",
        "Notes the team's lack of internal GraphQL experience as raising the option's cost (a team already running GraphQL internally gets it cheaper)",
        "Frames the paradigm switch as a long-horizon (about two-year) commitment rather than a quarter project",
        "Names the condition that would promote GraphQL anyway: external integrators confirming the data-access pain",
        "Keeps the stable spec-driven REST-plus-webhooks foundation as the base later surfaces derive from"
      ]
    },
    {
      "id": 3,
      "prompt": "I'm VP product at Tandemly, HR-compliance software sold to office managers and HR directors - none of them write code. Sales says deals close when we demo turnkey integrations with payroll tools, and prospects expect setup within an afternoon. Meanwhile our board keeps quoting 'every company should be API-first' and wants a public REST API on the roadmap before anything else. We have no public API today, one platform engineer, plus some contractor budget. What should our integration surface order be?",
      "expected_output": "A layered plan that leads with the embedded/turnkey surface for the non-technical buyer while still building the API foundation underneath, justified by buyer-type mapping, with candidate sequences, capacity-matched sequencing, and demand signals recorded per surface.",
      "files": [],
      "expectations": [
        "Leads the sequence with the embedded/turnkey layer, justified by the non-technical buyer and the hours-level time-to-value requirement",
        "Maps the buyer type explicitly (who chooses the product) before ranking surfaces, rather than jumping to a build order",
        "Treats API-first and embedded as layers rather than rivals, refusing both the board's blanket API-first framing and an embedded-only answer",
        "Plans the API foundation underneath the embedded layer, naming that retrofitting an API onto a UI-first product later is the expensive direction",
        "Uses the contrast between a developer-sold API platform and a business-owner-sold checkout button (Stripe vs PayPal or equivalent) as evidence the same industry supports opposite surface orders by buyer",
        "Warns that a surface reaching only the economic buyer or only the technical user stalls the deal",
        "Sequences one surface at a time matched to the one-engineer capacity",
        "Schedules no SDKs or MCP before a stable API contract exists",
        "Cites the retention/switching-cost argument for the API foundation: an API embedded in customer production code costs engineering hours to leave, not a cancellation click",
        "Presents 2-3 candidate sequences with trade-offs and a recommendation for the user to pick or blend, rather than one dictated plan",
        "Records the demand signal for the embedded surface (sales naming turnkey integrations as deal-closers) instead of scheduling it on taste"
      ]
    },
    {
      "id": 4,
      "prompt": "Platform PM at Quorrel, a developer-facing observability tool. Three signals are pulling different ways: (1) our community Discord and GitHub have loudly asked for a Terraform provider and a CLI for months - 400+ reactions on the issue; (2) sales says two enterprise renewals stalled last quarter because we can't export telemetry to the customer's warehouse; (3) API logs show 61% of REST traffic carries our Python library's user-agent. Leadership wants to pick by 'what the community wants' since community is our brand. What do we build first?",
      "expected_output": "A prioritization that puts the warehouse/bulk export first on the strength of the stalled renewals, ranks telemetry second and community asks third with reasons, applies the helper-library precedent to the 61% figure, and routes the bulk surface by demand shape.",
      "files": [],
      "expectations": [
        "Ranks the stalled enterprise renewals as the highest-weight signal and schedules the warehouse/bulk export surface first",
        "States the weighting rationale: pipeline blockers are low-frequency but high-severity, and a named blocked deal outranks any volume metric",
        "Ranks the 61% library user-agent share as the strongest volume signal, second behind the deal blockers",
        "Interprets the 61% figure through the documented helper-library precedent (roughly 77% of a major platform's REST traffic via library user-agents justifying SDK formalization and generation)",
        "Ranks community asks (Discord and GitHub reactions) third, as real but cheap to emit and easy to over-weight",
        "Pushes back on leadership's pick-by-community framing instead of adopting it",
        "Parks or defers the community-requested CLI and Terraform provider until confirmed against the higher-weight signals",
        "Distinguishes which downstream design owns the bulk surface by demand shape: file/lake export versus rows synced through an ELT tool",
        "Records the audience and the justifying demand signal for every scheduled or deferred surface",
        "Sets a review cadence or trigger tied to the deal-blocker log and telemetry changes reopening the plan"
      ]
    },
    {
      "id": 5,
      "prompt": "CTO at Mirelet, an 11-person fintech-infrastructure startup. We just raised and want to go big on platform: this quarter we plan to simultaneously launch webhooks, official SDKs in Python, Node, Go, Java and Ruby, a GraphQL endpoint, and an embeddable dashboard widget. Our REST API works fine, though the OpenAPI file lives in a wiki page and gets updated by hand when someone remembers. We also have no usage analytics on the API yet - we figured we'd add those after the new surfaces are live. Roadmap review is Friday. Sanity-check the plan?",
      "expected_output": "A rejection of the simultaneous launch that sequences one surface at a time within a stated capacity, blocks SDK generation on a CI-linted spec, fixes the drifting wiki spec first, drops GraphQL absent integrator pain, and moves telemetry instrumentation to the front.",
      "files": [],
      "expectations": [
        "Rejects the simultaneous multi-surface launch and sequences one new surface at a time within a stated capacity number",
        "States the reason: several concurrent launches yield half-measured surfaces with no clean signal from any, plus a standing maintenance bill for all",
        "Asks for or forces a sustained-capacity number: how many surfaces the team can build, document, support, and keep releasing for years",
        "Blocks the five-language SDK plan until the spec is a linted source of truth in CI, because SDKs derive from that contract",
        "Flags the hand-updated wiki OpenAPI file as spec drift to fix before any derived surface is scheduled",
        "Cites the one-spec-propagates-everywhere pattern (major platforms generating SDKs, docs, and MCP from one OpenAPI source of truth)",
        "Defers or removes the GraphQL endpoint absent a named, integrator-confirmed pain",
        "Moves per-client and per-surface usage telemetry instrumentation to an early plan item instead of after launch",
        "Keeps webhooks as the near-term addition riding the existing REST infrastructure",
        "Cites the capacity-matched precedent: SDK languages added only once tooling made supporting them sustainable, or the principle that two surfaces done properly beat six done badly",
        "Assigns surviving surfaces reversal-cost tiers, including server SDKs as high because method signatures bake directly into customer code"
      ]
    },
    {
      "id": 6,
      "prompt": "Head of product platform at Nuvaris, a B2B spend-management SaaS. Sales lost two enterprise deals to a competitor because the prospects wanted our transaction data available in Snowflake, and customer success reports AI assistants increasingly making calls against our API. We already run solid REST plus webhooks and generated SDKs off a clean OpenAPI spec. Four platform engineers. I want next year's surface roadmap covering warehouse sharing, a CLI, and 'agent access'. For the CLI, my staff engineer already drafted a spec with pretty ANSI table output. Lay out the plan per surface.",
      "expected_output": "A per-surface roadmap that schedules warehouse sharing on the lost deals, redesigns the CLI for dual human-and-agent audiences, schedules a derived MCP layer on the observed agent traffic, carries all five handoff fields per surface, and sets a review cadence with reopen triggers.",
      "files": [],
      "expectations": [
        "Schedules the warehouse/bulk sharing surface on the strength of the two lost deals, treating the pipeline blocker as the highest-weight signal",
        "Revises the CLI spec to serve dual audiences: readable table output for humans plus JSON with clean stdout/stderr separation for agents",
        "Notes the CLI has no dedicated downstream design owner, so its design decisions are recorded in the plan itself",
        "Schedules the agent-access surface (MCP) because observed agent traffic is a real demand signal, distinguishing this from hype-driven scheduling",
        "Positions MCP as a thin layer derived or generated from the existing stable contract, sequenced after the foundation and never hand-built",
        "Keeps concurrent new-surface builds within the four-engineer capacity, sequencing the three surfaces rather than launching all at once",
        "Every surface entry carries all five handoff fields: target audience, justifying demand signal, reversal-cost tier, capacity owner, and the owning downstream design or an inline decision",
        "Separates this plan's job (whether and when each surface ships) from per-surface design (how), which is handed off",
        "Sets a review date (quarterly or similar) plus named reopen triggers such as a new deal blocker or agent-signal changes",
        "Maps each surface to a distinct consumer class (BI consumers for warehouse sharing, humans and agents for the CLI, agent clients for MCP) rather than one ladder every consumer climbs",
        "Records what evidence the next review must re-check rather than re-arguing the whole plan"
      ]
    }
  ],
  "trigger_queries": [
    { "query": "We have a REST API and nothing else - customers are asking for webhooks, an SDK, and MCP support. What do we build, in what order?", "should_trigger": true },
    { "query": "Should our startup be API-first or ship embedded integrations first?", "should_trigger": true },
    { "query": "Our CEO wants an MCP server shipped this quarter - should it jump the roadmap?", "should_trigger": true },
    { "query": "Help me draft an integration-surface roadmap for next year", "should_trigger": true },
    { "query": "Sales says we lost deals over missing warehouse access - where does bulk export fit in our platform roadmap?", "should_trigger": true },
    { "query": "Is it time to add a GraphQL layer on top of our REST API?", "should_trigger": true },
    { "query": "We sell to non-technical buyers - do we even need a public API before the embedded integrations they ask for?", "should_trigger": true },
    { "query": "Which API surface should we build first as a B2B SaaS?", "should_trigger": true },
    { "query": "Customers keep asking for different ways to plug into our product - where do we start?", "should_trigger": true },
    { "query": "How do I decide between building a CLI, SDKs, or webhooks next?", "should_trigger": true },
    { "query": "Everyone's shipping MCP servers - do we actually need one, and when?", "should_trigger": true },
    { "query": "What's the right order to roll out developer-facing surfaces for our platform?", "should_trigger": true },
    { "query": "Our board wants us to become a platform - what do we expose to third parties first?", "should_trigger": true },
    { "query": "Prioritize our platform bets: GraphQL, SQL access for customers, or agent support?", "should_trigger": true },
    { "query": "A big prospect's RFP requires MCP compatibility - how does that change our API roadmap?", "should_trigger": true },
    { "query": "We only have capacity to build one integration surface this year - which one?", "should_trigger": true },
    { "query": "should we do graphql or is that overkill for us", "should_trigger": true },
    { "query": "Partners complain half our product isn't reachable via API - how do we sequence fixing that against adding new surfaces?", "should_trigger": true },
    { "query": "I need a plan for which developer surfaces to offer and when", "should_trigger": true },
    { "query": "We're debating REST vs GraphQL vs gRPC for our public platform - how do we choose?", "should_trigger": true },
    { "query": "Our mobile team wants GraphQL, sales wants Snowflake shares, and the CEO wants AI agents supported - help me sequence this", "should_trigger": true },
    { "query": "What integration options should we offer AI agents versus human developers?", "should_trigger": true },
    { "query": "how do platforms decide the order they ship apis, sdks, webhooks and so on?", "should_trigger": true },
    { "query": "We're API-first but deals keep stalling with non-technical buyers - what layer are we missing?", "should_trigger": true },
    { "query": "Is webhooks-before-SDKs the right call for a young API platform?", "should_trigger": true },
    { "query": "My CTO wants to launch five integration surfaces at once - talk me through what order actually makes sense", "should_trigger": true },
    { "query": "Which comes first: an embedded widget for our customers or a public API for their developers?", "should_trigger": true },
    { "query": "We want to open our product to third-party developers - what do we build first?", "should_trigger": true },
    { "query": "Does the agent traffic showing up on our API mean we should prioritize MCP now?", "should_trigger": true },
    { "query": "Roadmap question: do SDKs come before or after we stabilize the OpenAPI spec?", "should_trigger": true },
    { "query": "A deal is blocked because we lack one integration surface - how do I re-rank the roadmap?", "should_trigger": true },
    { "query": "What should our platform team ship next: more REST endpoints, GraphQL, or an embedded integration layer?", "should_trigger": true },
    { "query": "Which languages should our official SDKs support first?", "should_trigger": false },
    { "query": "How should we sign our webhook payloads - which HMAC scheme?", "should_trigger": false },
    { "query": "Design a retry and backoff policy for our webhook deliveries", "should_trigger": false },
    { "query": "Help me design Relay cursor pagination for our public GraphQL schema", "should_trigger": false },
    { "query": "What depth and complexity limits should our GraphQL API enforce?", "should_trigger": false },
    { "query": "Review our REST API's resource naming and status-code usage", "should_trigger": false },
    { "query": "How do we version our proto files and catch breaking changes with buf?", "should_trigger": false },
    { "query": "What take rate should our app marketplace charge partners?", "should_trigger": false },
    { "query": "Should our MCP server expose one tool per endpoint or a curated set of workflow tools?", "should_trigger": false },
    { "query": "How do I add OAuth 2.1 with PKCE to the MCP server we already built?", "should_trigger": false },
    { "query": "Design our API-key format, prefixes, and rotation policy", "should_trigger": false },
    { "query": "What rate-limit tiers and 429 headers should our public API publish?", "should_trigger": false },
    { "query": "Our API error messages confuse integrators - design an error-code taxonomy", "should_trigger": false },
    { "query": "How long should we store idempotency keys, and what backoff should our SDKs default to?", "should_trigger": false },
    { "query": "Set up a deprecation and sunset-header policy for v1 of our API", "should_trigger": false },
    { "query": "Design the consent screen and scope taxonomy for our OAuth provider", "should_trigger": false },
    { "query": "How should our status page model partial outages and incident updates?", "should_trigger": false },
    { "query": "Design magic test values and simulated events for our API sandbox", "should_trigger": false },
    { "query": "Audit our API reference docs for undocumented endpoints and stale examples", "should_trigger": false },
    { "query": "Plan our developer portal's onboarding flow to cut time to first call", "should_trigger": false },
    { "query": "Should we list our SaaS as a source connector on Fivetran and Airbyte?", "should_trigger": false },
    { "query": "Improve our Salesforce AppExchange listing's install conversion", "should_trigger": false },
    { "query": "Design the review and approval process for third-party apps on our marketplace", "should_trigger": false },
    { "query": "Pick launch partners and featured apps for our marketplace debut", "should_trigger": false },
    { "query": "How do we expose per-integration request logs and replay to our partners?", "should_trigger": false },
    { "query": "Which payroll ISVs should we partner with, and how deep should each integration go?", "should_trigger": false },
    { "query": "Write a job description for an API product manager", "should_trigger": false },
    { "query": "How do I prep for a platform engineer interview at an API company?", "should_trigger": false },
    { "query": "Design tenant isolation and row-level security for our customer-facing SQL access", "should_trigger": false },
    { "query": "Parquet file drops or Snowflake shares - which bulk delivery mechanism should we pick?", "should_trigger": false },
    { "query": "Design the partitioning and schema-evolution contract for our S3 data exports", "should_trigger": false },
    { "query": "Set up onboarding, sandbox provisioning, and certification for our partner developers", "should_trigger": false }
  ]
}

# Build-order case studies

Documented surface-rollout timelines behind the default sequence in step 4. The non-fintech cases lead: two structurally different domains (data infrastructure, telephony) converging on the same order is the strongest evidence the sequence is a property of reversal cost and audience economics, not an artifact of payments regulation.

## Segment (martech / data infrastructure)

1. **~2012 - tracking API + SDK**: `analytics.js`, an open-source tracking library plus a hosted tracking API, was the founding product.
2. **Sources & Destinations routing**, built directly on the tracking API.
3. **2015 (rolling into 2016) - Warehouses**: SQL/warehouse loading into Redshift/Postgres - the bulk surface, added once customers were already exporting event data manually.
4. **December 12, 2018 - Config API**: a REST management API launched with an explicit no-breaking-changes commitment from day one.
5. **~2021 - Public API**: REST successor to the Config API (exact GA date not exposed publicly - uncertain); Config API tokens stopped being issued February 2024.
6. **2022 - Reverse ETL**, extended via Unify in 2023.
7. **2025+ - AI-agent surface**: delivered via parent company Twilio's MCP server indexing Segment's docs, not a standalone first-party server.

Order: tracking API/SDK → routing → warehouse/SQL (bulk) → REST management API → reverse ETL → MCP (derived, via parent).

## Twilio (communications)

1. **November 2008 - Voice API**: the founding product.
2. **February 2010 - SMS API** - the REST API has stayed pinned to base version `2010-04-01` ever since - a live example of how binding a public REST contract becomes.
3. **Helper libraries / SDKs** on top of REST, migrated (~2016-17) to homegrown OpenAPI auto-generation once hand-maintaining idiomatic libraries stopped scaling - reaching 200+ endpoints across 7 languages. The trigger was telemetry: 77% of REST requests already carried a helper-library user-agent. The rollout was capacity-matched: languages were added only once tooling let Twilio "support them sustainably."
4. **March 2025 - Twilio Alpha MCP server** (developer preview) indexing 1,400+ endpoints from Twilio's own public OpenAPI specs. A later Public Beta covers 1,800+ endpoints plus SendGrid and Segment documentation.

Order: REST → REST (second product) → SDKs (hand-built, then generated) → MCP (derived).

## Stripe (fintech)

REST + embedded UI early (Stripe.js/Elements/Checkout - the API-first foundation plus the embedded layer for non-developers) → webhooks/Events API → SDKs (auto-generated across languages, with monthly API versioning and breaking changes only twice a year) → MCP server / Agent Toolkit (February 2025, built on the existing Python and Node SDKs, hosted at `mcp.stripe.com`). Stripe has no public GraphQL API - it stayed REST throughout.

Stripe's webhook-migration pattern is worth copying when any surface changes version:

1. Create a new endpoint pinned to the target version.
2. Migrate traffic.
3. Decommission the old one only once confident.

Never mutate the live endpoint in place.

## Plaid (fintech)

REST + Plaid Link (the embedded client-side onboarding component, central from early on) → webhooks → server SDKs, then client SDKs (iOS/React Native) later → a 2025 CLI explicitly designed for dual audiences: readable table output for developers, JSON with clean stdout/stderr separation for AI agents. Plaid is the named model for the CLI surface serving humans and agents at once.

## The MCP launch wave (dated evidence for "derive, don't hand-build")

- **February 20, 2025** - Stripe ships its MCP server / Agent Toolkit, built directly on its existing SDKs.
- **May 2025** - Cloudflare's MCP Demo Day: Asana, Atlassian, Block, Intercom, Linear, PayPal, Sentry, Stripe, and Webflow all launch remote MCP servers on Cloudflare's infrastructure in one coordinated event.
- **February 2026** - Atlassian's remote MCP server reaches GA.
- **May 6, 2026** - AWS's MCP Server reaches general availability (preview from November 2025), with a single `call_aws` tool executing 15,000+ AWS API operations using the caller's existing IAM credentials.

Every named platform generated its MCP surface from an already-existing API rather than building agent access as a separate product - the pattern the step-4 rule ("MCP-first is not on the menu") rests on.

## What transfers

- REST (or an event/tracking API) plus webhooks first → the embedded layer where the buyer needs it → SDKs once the contract stabilizes → bulk/warehouse when BI demand shows → MCP last and derived. Fintech and non-fintech independently converged on this shape.
- The one deviation pattern is audience-driven, not novelty-driven: Segment added its bulk/SQL surface mid-sequence because its BI consumers demanded it - the audience map, not the protocol fashion of the year, reordered the middle.

# Surface condition tables

Decision aids for step 4 of the workflow. The tables encode sourced patterns. Where a table is synthesis across sources rather than one cited framework, it says so - keep that label when copying rows into a plan.

## Per-surface reversal-cost tiers

Reversal cost is what a wrong commitment costs to unwind once unknown third parties depend on the surface (Hyrum's Law). This table is an inferred synthesis across breaking-change literature, not one cited source - reasonable practitioners may order the middle tiers differently.

| Surface                  | Reversal cost                    | Why                                                                                     |
| ------------------------ | -------------------------------- | --------------------------------------------------------------------------------------- |
| Webhooks                 | Low-medium                       | Event types extend additively; consumers tolerate new fields                            |
| REST                     | Low (additive) / High (breaking) | Endpoints and optional params extend safely; removals and renames break unknown clients |
| Bulk / warehouse shares  | Medium                           | Schema changes ripple into customer SQL and BI dashboards                               |
| MCP tool definitions     | Medium (today)                   | Derived and regenerable from the spec, but agent workflows depend on stable tool names  |
| Embedded UI / components | Medium                           | Versioned components, but a visual and behavioral contract partners build around        |
| GraphQL schema           | High                             | A tight public contract; deprecations are visible but binding                           |
| Server SDKs              | High                             | Method signatures baked directly into customer code                                     |

The practical consequence: commit early to the low-tier surfaces, and delay every high-tier commitment until the contract it projects has stabilized. This is also why mature platforms generate REST docs, SDKs, and MCP from one OpenAPI source of truth (Stripe, Twilio, Cloudflare) - one change propagates everywhere instead of needing a separate migration per surface.

## Buyer type: API-first vs embedded-first

Use as a quick decision aid, not a strict rule. Map interview answer 1 here before ranking postures.

| Condition          | API-first wins                                | Embedded-first wins                          |
| ------------------ | --------------------------------------------- | -------------------------------------------- |
| Buyer type         | Technical - a developer chooses the tool      | Non-technical business buyer                 |
| Time-to-value need | Days acceptable                               | Hours required                               |
| Product complexity | Customer wants full control and customization | Customer wants turnkey, compliance handled   |
| Market maturity    | Mature; developers expect programmable access | Nascent; buyer needs guardrails              |
| Distribution       | Developer word-of-mouth, bottom-up            | Sales-led, embedded into a partner's product |

Two caveats that keep this table honest:

- **Layer, don't choose.** The 2025-2026 trend is API-first as the architectural foundation with an embedded/unified layer added later to accelerate go-to-market - not one paradigm excluding the other. Stripe won developers API-first, then layered drop-in embedded flows for non-developers. Retention argument for keeping the API foundation: an API embedded in customer production code has a switching cost measured in engineering hours, not a cancellation click.
- **Depth check before claiming API-first.** Retrofitting APIs onto a UI-first product typically exposes only a fraction of real functionality - a documented lending-industry critique describes partners discovering mid-integration that intake is API-accessible but underwriting still needs a manual step. Probe depth per capability in step 2.

## Demand-signal weighting

- **Pipeline/sales blockers - highest weight.** Low-frequency, high-severity: "a retention or sales risk - few hit it, but the ones who do churn or block deals." A named blocked deal outranks any volume metric.
- **Usage telemetry by client type - strongest volume signal.** Twilio's canonical instance: "At Twilio, 77% of all requests to our REST API are made by a helper library user-agent" - the data that justified formalizing, then auto-generating, its SDKs.
- **Community/engagement signals - third.** Stars, asks, forum chatter: real but cheap to emit. Confirm against the two signals above before scheduling a surface on them alone.
- **Standard prioritization frameworks (RICE, ICE, impact-effort) sit on top of these signals** - they rank what the signals surface. They never replace gathering them.

## GraphQL and gRPC promotion conditions

- **GraphQL**: promote only on a named, integrator-confirmed pain - client-driven data access, mobile over/under-fetching, the N+1 problem - never as a default REST replacement. Budget roughly 20-40% overhead on the initial build plus N+1 and authorization complexity. Paradigm switches are two-year-horizon decisions. Shopify is the counter-example to cite in both directions: it went GraphQL-first for its Admin API (REST marked legacy October 2024, GraphQL required for new apps by April 2025) and drew significant developer pushback over verbosity.
- **gRPC**: a niche public surface - promote when the audience is backend teams needing streaming or strict latency budgets, and the platform can support the proto toolchain integrators need. Otherwise leave it internal. The sibling gRPC skill owns the design if promoted.

## MCP: scheduling, build-vs-buy, monetization

- **Scheduling**: MCP is a thin layer derived from an existing REST or GraphQL surface, added once that foundation is stable and step-3 agent signals justify it. Adoption is real and fast (multi-vendor governance under the Linux Foundation since December 2025, with RFPs starting to require "MCP-compatible"), which is exactly why the demand signal - not the hype - sets the date.
- **Build vs buy**: a demo-grade server is a weekend. A production-grade hand-build runs from roughly 150-250 hours for a narrow internal tool to several months for a public, multi-tenant, or heavily-permissioned one, plus an estimated $50K-150K/year to maintain (independently corroborated across multiple 2026 cost guides for the enterprise-maintenance tier, though the same guides disagree with each other by more than an order of magnitude on total build cost - $25K-$120K in one, $300K-$700K+ in another, for what each calls a comparable production build). Managed platforms absorb the infrastructure and protocol churn. The economics tilt toward managed at roughly 3-5 enterprise integrations. Build in-house only when AI access to a system nobody else owns (vertical SaaS, proprietary dataset, regulated workflow) is itself the paid product. Every figure in this bullet is a vendor- or analyst-reported estimate, not measured data - carry the ratio (a weekend demo against months of production work) into the plan, never the number.
- **Security caveat to carry into the plan**: only about 8.5% of servers implement MCP's mandatory OAuth 2.1 requirement in practice - re-verified as still current, and corroborated across multiple independent March 2026 audits (NimbleBrain's direct query of the official MCP registry across 3,012 unique servers, Practical DevSecOps, Cybertizeweb, Affinco), not a single vendor's self-reported figure. Unauthorized internal servers ("MCP Shadow IT") are a named enterprise risk, an argument for the managed rung and for treating the MCP surface as a real product, not a hackathon artifact.
- **Monetization**: per-call agent payments are unproven. Typical per-call values are "barely worth metering". The x402 protocol's observed volumes peaked near $800K-$1M/day in Q4 2025 (largely developer testing, per Chainalysis), then collapsed - a March 2026 CoinDesk snapshot found roughly $28K/day with about half attributed to wash trading, and by mid-2026 the 7-day average sat near $41K-$42K/day, down roughly 93% year-to-date from the December 2025 peak. Stripe's Machine Payments Protocol (announced March 2026) remains early-stage with no comparable volume data published. Re-check both before citing; this is a moving, still-declining baseline, not a stable snapshot. Defer per-call MCP monetization until call values clear metering overhead. Label any such revenue line speculative.

---
name: api-integration-surface-strategy
description: Decide which integration surfaces a platform offers external developers and AI agents - REST, GraphQL, gRPC, SQL access, bulk data sharing, webhooks, SDKs, CLI, MCP, embedded components - and in what build order, sequenced by reversal cost and audience rather than novelty. Use whenever the user mentions which API to build first, adding a GraphQL or MCP layer, an integration-surface roadmap, API-first vs embedded-first, or a missing surface blocking deals - even if they never say "integration surface". Umbrella strategy only - once a surface is chosen, per-surface design belongs to siblings such as samber/developer-platform-skills@webhook-platform-design and samber/developer-platform-skills@sdk-portfolio-strategy.
license: MIT
metadata:
  author: Samuel Berthe
  version: "1.0.2"
---

# API Integration Surface Strategy

You are an integration-surface strategist for a platform team. Decide which surfaces the platform offers external developers and AI agents - REST, webhooks, GraphQL, gRPC, SQL access, bulk data sharing, SDKs, CLI, MCP, embedded components - and in what order to build them, as one written, sequenced plan with a named audience and demand signal per surface.

This is the umbrella decision above every per-surface skill in this collection. Each surface's design belongs to a sibling (see References); this skill decides whether and when a surface enters the mix, then hands off. The organizing principle throughout is reversal cost plus audience, never novelty: additive REST changes are cheap to unwind, while a public contract someone already depends on is near-impossible to change.

Hyrum's Law - "with a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody" - is the mechanism. It is why mature platforms delay committing to higher-abstraction surfaces until the layer underneath stabilizes.

**Memory (advised): When memory lives in a file, consider using `developer-platform-context.md`; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**

## Interview

Ask one question per message and wait for the answer - each one changes a later step. Offer the multiple-choice options where given.

1. Who chooses your product - the buyer type? (a) a developer picks the tool bottom-up, (b) a non-technical business buyer, (c) both in the same deal (economic buyer plus a technical user proving it). This drives the API-first vs embedded-first posture more than anything else.
2. Which surfaces exist today, and how deep? For each: fully self-serve, partial (API exists but some steps still manual), or absent. Probe depth per capability - a partially API-accessible flow breaks the integration a partner expected.
3. What state is your machine-readable spec (OpenAPI or equivalent) in? (a) linted source of truth in CI, (b) exists but drifts from the API, (c) none. Every derived surface - SDKs, MCP, generated docs - depends on this answer.
4. Which demand signals can you actually read? (a) pipeline/sales data naming the missing surface that blocks deals, (b) usage telemetry by client type (e.g. SDK/library user-agent share), (c) community asks and developer-engagement signals, (d) none instrumented yet.
5. Any AI-agent demand yet? (a) RFPs or security reviews requiring MCP compatibility, (b) observed agent traffic on existing surfaces, (c) customer questions only, (d) none.
6. How many surfaces can your team genuinely sustain concurrently - build, document, support, and keep releasing for years? A number, not an ambition.
7. By when must the first new surface land - is a launch, deal, or RFP deadline forcing the order?
8. Is this a one-off unblock (ship the surface a deal needs) or a compounding asset (a surface roadmap the team runs for years)?
9. What is your effort ceiling: engineer-hours available, appetite for standing per-surface maintenance, and how reversible each choice must be?

Answers 7-9 re-rank the menu in step 4 - a hard deadline promotes the fastest additive surface; a compounding mandate promotes spec work that every later surface derives from.

## Audience split by buyer type

The sourced split that changes the strategy is buyer type: whether a developer chooses the tool or a non-technical buyer does.

- **Stripe**: won by selling an API to developers ("seven lines of code", dashboard later).
- **PayPal**: sold a checkout button to business owners - same industry, opposite surface order.

Map interview answer 1 onto the condition table in [references/surface-condition-tables.md](references/surface-condition-tables.md) before ranking anything. Treat API-first vs embedded-first as layers, not rivals.

The documented pattern is API-first as the durable foundation, with an embedded/no-code layer added on top for the non-technical side of the deal. Stripe itself did both - a surface choice that reaches only the technical user or only the economic buyer stalls the deal.

## Brainstorm candidate sequencing plans

Before writing the plan, present 2-3 candidate sequences with trade-offs and a recommendation, and let the user pick or blend. Build candidates from the step-4 postures:

- A spec-first derivation sequence.
- An embedded-led sequence for a non-technical buyer.
- A deal-driven sequence that front-loads the one surface sales named.

Then draft the plan section by section (one per workflow step below), validating each with the user before moving on. Do not finalize until every section is approved.

If your harness has persistent memory, record the approved decisions so later per-surface runs load them instead of re-interviewing:

- Surface list and order.
- Per-surface audience and demand signal.
- Capacity ceiling.
- Review date.

## Workflow

1. Map audiences and buyers.
2. Inventory current surfaces and the spec.
3. Read the demand signals.
4. Rank and sequence the surfaces.
5. Write the per-surface handoffs.
6. Set the review cadence.

Each step has a section below, in order. Every step ends in a written section of the plan - a step that ends in a conversation is not done.

## 1. Map audiences and buyers

List every consumer class the platform serves or wants:

- First-party developers.
- Third-party integrators.
- Non-technical operators.
- BI/analytics consumers.
- AI agents.

For each, record who writes the calling code (a person, a generator, an agent) and which buyer from interview answer 1 they belong to.

Different surfaces persist for different consumers rather than replacing one another:

- REST and GraphQL serve human-written software.
- SQL and bulk files serve BI consumers.
- MCP serves agent clients.

The plan is a per-audience map, not a single ladder every consumer climbs.

## 2. Inventory current surfaces and the spec

Table every existing surface, with a column for each:

- Audience served.
- Depth (self-serve end-to-end, or partial).
- Spec-derived or hand-built.
- Observed traffic share, if telemetry exists.

Flag shallow coverage explicitly - an API that covers intake but leaves later steps manual is a named failure mode, not a checkbox ticked.

Record the spec's state (interview answer 3) as the plan's central dependency. SDKs, MCP tools, and reference docs are all generated from one OpenAPI source of truth at Stripe, Twilio, and Cloudflare, so one change propagates everywhere instead of needing a migration per surface. A drifting spec is fixed before any derived surface is scheduled.

## 3. Read the demand signals

Weigh the signals. Do not just collect them:

- **Pipeline/sales data weighs highest** - low-frequency but high-severity: the accounts that hit a missing surface churn or block deals. A named deal blocker outranks any volume metric.
- **Usage telemetry by surface and client type** is the strongest volume signal. Twilio's SDK investment came from exactly this: 77% of its REST API requests carried a helper-library user-agent, which justified formalizing then auto-generating the libraries.
- **Community and engagement signals** (asks, stars, forum chatter) rank third - real, but cheap to emit and easy to over-weight.
- **AI-agent demand** (interview answer 5) is what schedules MCP: RFPs starting to require MCP compatibility move it up; zero agent signals leave it parked, whatever the hype cycle says.

If answer 4 was "none instrumented", make instrumenting per-client telemetry an early plan item - later re-ranks want that data.

## 4. Rank and sequence the surfaces

Rank the lead postures - which surface family anchors the sequence - before ordering individual surfaces:

- effort (standing, what you spend): `GraphQL-led > embedded-first > REST+webhooks-first`
- reversal cost (what a wrong commitment costs to unwind): `GraphQL-led > embedded-first > REST+webhooks-first`
- value (downstream surfaces unlocked from the same contract): `REST+webhooks-first > GraphQL-led > embedded-first`
- efficiency: `REST+webhooks-first > embedded-first > GraphQL-led`

- **Default rung: REST plus webhooks first.** REST is the near-universal substrate (93% adoption vs 33% for GraphQL, Postman 2025) and extends additively - new endpoints and optional params are safe, so early mistakes stay cheap. Webhooks ride the same infrastructure rather than opening a new paradigm. Everything later derives from this contract.
- **Embedded-first** - white-label components or an embedded-iPaaS layer leading. Promote it when interview answer 1 says the buyer is non-technical and time-to-value must be hours, not days (the condition table); it trades raw flexibility for integrations that "just work". Even then, plan the API foundation underneath - retrofitting one later is the expensive direction.
- **The starved option: GraphQL-led.** Highest per-client value where client-driven data access, mobile over/under-fetching, or N+1 pain is real - and high standing effort (teams report roughly 20-40% overhead on the initial build, plus N+1 and authorization complexity) with a schema that is a tight, binding public contract. It loses every efficiency round. That named pain, confirmed by integrators, is what promotes it anyway. Shopify went GraphQL-first for its Admin API and drew significant developer pushback over verbosity - cite it in both directions.

MCP-first and SDK-first are not on this menu at all, not merely demoted: both derive from a contract that must already exist and be stable. Sequence them inside the plan instead - SDKs generated once the contract stabilizes, MCP last as a thin derived layer whose timing is set by the step-3 agent signals. Every named platform that shipped MCP (Stripe February 2025, the Cloudflare May-2025 cohort, AWS at GA in May 2026) generated it over an existing API rather than hand-building a separate product.

This ranking is a default, not a law - it shifts with context and with who executes it. Re-rank against the interview:

- Answer 1 flips the top two rungs per the condition table.
- A team already running GraphQL internally gets the starved option cheaper.
- A deal deadline (answer 7) can pull one specific surface ahead of the whole order.

Then sequence within the winning posture, one surface at a time - never several concurrently beyond the capacity number from answer 6. Opening many at once yields several half-measured surfaces and no clean signal from any.

Twilio added SDK languages only once tooling let it support them sustainably. Two surfaces done properly beat six done badly.

See [references/surface-condition-tables.md](references/surface-condition-tables.md) for the per-surface reversal-cost tiers, the buyer-type condition table, and the MCP build-vs-buy thresholds; see [references/build-order-case-studies.md](references/build-order-case-studies.md) for the Segment, Twilio, Stripe, and Plaid sequences the default order comes from.

## 5. Write the per-surface handoffs

For every surface the plan schedules, record:

- Target audience.
- The demand signal that justified it.
- Its reversal-cost tier.
- A capacity owner.
- The sibling skill that owns its design (see References).

The division of labor is fixed:

- This skill decides _that_ and _when_.
- The sibling decides _how_.

The gRPC surface's design belongs to `samber/developer-platform-skills@public-grpc-api-design`; the bulk-data/lake surface's belongs to `samber/developer-platform-skills@bulk-data-sharing-design` (file/lake exports) or `@etl-connector-strategy` (rows synced through an ELT tool), depending on which shape the demand signal points to.

Embedded components have no dedicated sibling - record their design decisions in the plan itself. A CLI's design belongs to `samber/developer-platform-skills@cli-interface-design`; record here only its audience and the dual-audience promise (Plaid's 2025 pattern - readable tables for humans, JSON with clean stdout/stderr separation for agents).

A technology-specific agent skill shipped with a CLI, SDK or library belongs to `samber/developer-platform-skills@agent-skill-offering`, which keeps it versioned with the code.

A Terraform/OpenTofu provider for the platform's long-lived configuration objects belongs to `samber/developer-platform-skills@terraform-provider-offering`. It derives from the REST contract like SDKs do, so schedule it after that contract is stable; record here only its audience (platform and infrastructure teams) and demand signal.

## 6. Set the review cadence

A surface plan decays as signals change. Set a review date (quarterly is a reasonable default) and the triggers that reopen it early:

- A deal blocked on a missing surface.
- Agent-demand signals appearing (answer 5 moving from "none" to "RFPs").
- Telemetry contradicting the audience map.
- A scheduled surface's owner losing capacity.

Record what evidence next review must re-check rather than re-arguing the whole plan.

## Failure modes

- **Novelty-driven MCP-first.** Building the newest surface first because it is new inverts the whole framework - build order is governed by reversal cost and audience, and MCP presupposes an API to wrap. Park it until step-3 agent signals move it.
- **Hand-building the MCP surface.** Every named platform derived its MCP server from an existing spec. A hand-built one is months of work re-creating what a generator produces. Build in-house only when AI access to your proprietary system _is_ the paid product.
- **Betting revenue on per-call agent monetization.** The payment rails exist (Stripe's MPP, the x402 protocol) but the unit economics are unproven - observed per-call volumes are tiny and partly wash-traded. Label any MCP monetization line in the plan as speculative.
- **Surface sprawl without telemetry.** Adding surfaces on gut feel, several at once, leaves no clean signal from any of them and a standing maintenance bill for all. One at a time, capacity-matched, telemetry instrumented first.
- **Shallow API-first.** Declaring API-first while only part of each flow is API-accessible - partners discover mid-integration that a later step still needs a manual touch. Step 2's depth probe exists to catch this before a partner does.
- **Treating API-first and embedded as rivals.** Picking one forever over-serves one side of the deal. The documented pattern is layered: API foundation, embedded accelerant on top.

## Measurement

- Plan coverage gate: every surface in the plan - scheduled, deferred, or declined - carries all five handoff fields (audience, demand signal, reversal-cost tier, owner, owning sibling or inline decision). 100% or the plan is incomplete. Iterate until it passes.
- Derivation gate: zero derived surfaces (SDKs, MCP, generated docs, an embedded layer over the API) scheduled before the contract they derive from is declared stable in step 2. Binary.
- Concurrency gate: concurrent new-surface builds never exceed the capacity number from interview answer 6.
- Trends to watch after adoption (not pass thresholds): per-surface traffic share by client type, the deal-blocker log emptying or refilling, and agent-signal changes that should reopen the plan early.

## Invocation examples

- "We have a REST API and nothing else - customers are asking for webhooks, an SDK, and 'MCP support'. What do we build, in what order?"
- "Our CEO wants us to be AI-native and ship an MCP server this quarter. Should that jump the roadmap?"
- "We sell to operations managers, not developers. Do we still need a public API before the embedded integrations our buyers ask for?"
- "Sales says we lost two deals over missing warehouse access. Where does bulk data sharing fit in our surface roadmap?"

## References

- [references/surface-condition-tables.md](references/surface-condition-tables.md) - per-surface reversal-cost tiers, the buyer-type condition table for API-first vs embedded-first, demand-signal weighting, MCP build-vs-buy thresholds and monetization caveats.
- [references/build-order-case-studies.md](references/build-order-case-studies.md) - documented surface-rollout timelines: Segment and Twilio (non-fintech, lead cases), Stripe and Plaid (fintech), and the dated MCP platform-launch wave.
- `samber/developer-platform-skills@public-api-design-review` - the REST surface's whole-contract consistency review.
- `samber/developer-platform-skills@webhook-platform-design` - the webhook surface: delivery, signing, retries, subscription lifecycle.
- `samber/developer-platform-skills@sdk-portfolio-strategy` - which SDK languages and build model, once SDKs are chosen as a surface here.
- `samber/developer-platform-skills@public-graphql-api-design` - the GraphQL surface's schema, pagination, and security design.
- `samber/developer-platform-skills@sql-jdbc-access-design` - the SQL/JDBC surface: tenant isolation, schema stability for BI consumers.
- `samber/developer-platform-skills@mcp-server-offering` - building the MCP surface itself, once agent signals schedule it here.