Build the Integration and API Ecosystem

Task

Define integration/API ecosystem roadmap.

Summary

Prioritize integrations according to customer workflow, sales friction, product value, and partner leverage.

Build an Integration Roadmap That Helps Customers Buy and Use the Product

Task ID: S5-12

An integration roadmap should not be a popularity contest for software logos. It should identify the connections that remove real sales objections, fit important customer workflows, and give capable partners a reason to invest. This article explains how to select, deliver, govern, and measure a small set of integrations without creating an unsupported technical estate.

The business problem is not a shortage of integration ideas

A growing software company rarely lacks requests for integrations.

A prospect wants customer data sent to its customer relationship management system. Another needs invoices posted to its accounting software. An enterprise buyer cannot proceed without single sign-on. A partner wants an application programming interface, or API, so it can build an extension. Sales wants every recognizable logo on the integrations page because competitors display them.

All of these requests may be reasonable. They are not equally valuable.

The company can easily spend months building connections that help one deal, duplicate work already available through automation platforms, or create permanent support obligations without producing repeatable revenue. It can also publish an API before its data model, permissions, documentation, or support process is ready. The result looks like progress—a connector, a developer portal, perhaps a marketplace listing—but does not create a dependable channel.

The central operating principle is:

Prioritize an integration when it improves an important customer workflow and creates repeatable commercial value at an acceptable operating cost.

This changes the question from “Which systems should we integrate with?” to four more useful questions:

• Where does the product sit in the customer’s work?
• Which missing connection stops customers from buying, activating, renewing, or expanding?
• Can another company help distribute, implement, or extend the product?
• Can the integration be operated reliably after its initial release?

Research on digital platform ecosystems supports this broader view. APIs are only one part of the relationship between a platform and outside developers. Documentation, software development kits, testing tools, support, commercial rules, certification, release notices, and marketplace processes also influence whether third parties can build useful products and continue supporting them. Researchers often call these technical and social “boundary resources”: the interfaces and rules through which a platform owner and external developers work together.

That distinction matters because an API endpoint is not an ecosystem. An ecosystem begins to form only when another company can understand the opportunity, build against a stable product, reach customers, receive support, and capture enough value to justify continuing its investment.

Rank workflow outcomes, not software logos

A useful roadmap starts with the customer’s work rather than a catalogue of vendors.

Suppose a company sells software that approves field-service jobs. Customers may use a customer relationship management system to create the job, the product to review it, an accounting system to issue an invoice, and a business-intelligence tool to report on the result. The relevant unit of analysis is not “Salesforce integration” or “QuickBooks integration.” It is the movement of a job from request through approval, completion, billing, and reporting.

This workflow view reveals what the integration must actually do:

• Which event starts the transfer?
• Which records must move?
• Which system owns each field?
• Is the flow one-way or two-way?
• How quickly must data arrive?
• What happens when records conflict?
• Which user authorizes access?
• What must be visible when a transfer fails?

Without those answers, an integration request is usually just a brand name attached to an assumption.

A roadmap should evaluate three types of value together.

Sales friction is evidence that the missing connection is delaying or preventing revenue. It appears in lost-deal notes, security reviews, requests for custom implementation, extended trials, procurement objections, and repeated questions from qualified prospects. A request from a large opportunity deserves attention, but one deal alone does not prove a repeatable market need.

Customer-workflow value describes what the connection changes after the sale. A strong integration can remove duplicate data entry, shorten onboarding, make the product part of a daily process, improve data completeness, or allow a customer to retire manual work. The most useful evidence comes from observing the workflow, not simply asking customers which integrations they would like.

Partner leverage exists when another company can contribute distribution, product capability, implementation capacity, credibility, or access to a customer group that would be expensive to reach alone. The relationship must also work for the partner. Research on platform ecosystems finds that outside developers invest their time and knowledge when participation improves their own customer proposition and allows them to capture value. Standardized resources such as APIs and documentation can support many partners, while selected partners may also require direct technical and commercial support.

These sources of value overlap, but they should not be collapsed into a single vague claim that an integration is “strategic.” A connection may remove sales friction without producing partner distribution. Another may improve retention but have little effect on new sales. A marketplace listing may create reach while adding review, billing, support, and revenue-sharing requirements.

The roadmap should state which result is expected and what evidence would confirm it.

Build the roadmap from three evidence streams

The work begins with evidence already present in sales, product, support, and customer operations. No dependency may be recorded formally, but the quality of the roadmap depends on the quality of these underlying records. A company with inconsistent loss reasons, weak product telemetry, or no view of customer workflows should treat those gaps as constraints rather than pretending that its ranking is precise.

Sales and customer evidence

Review at least the previous two or three sales cycles, using a period long enough to contain a representative mix of wins, losses, and stalled opportunities.

Extract every credible integration reference from:

• opportunity notes and call recordings;
• loss and no-decision reasons;
• security and procurement questionnaires;
• implementation estimates;
• trial and onboarding records;
• support tickets and feature requests;
• renewal and expansion discussions;
• customer advisory meetings.

Normalize the language. “Connect to CRM,” “Salesforce sync,” “send contacts to sales,” and “avoid re-entering account data” may describe the same underlying workflow.

Do not rank requests by mention count alone. Ten requests from poor-fit prospects may matter less than four requests from customers in the company’s strongest segment. Record the requesting customer’s segment, potential or actual revenue, use case, stage in the buying process, current workaround, and consequence of not having the connection.

Interviewing should test behaviour rather than collect wish lists. Ask the customer to walk through the last time the task occurred. Identify the systems opened, data copied, approvals required, delays encountered, errors corrected, and people involved. This produces a workflow requirement that can be tested.

Product and operating evidence

Product data should show whether the proposed connection would touch a frequent and valuable activity.

Useful questions include:

• How many active customers perform the relevant task?
• How often does it occur?
• Is the work concentrated in a particular customer segment or plan?
• Does the current workaround generate errors, support contacts, or manual service work?
• Which customer or product data would leave the system?
• Can the product detect and recover from failed transfers?
• Would the connection affect a core transaction or a peripheral convenience?

An integration that sits on a critical workflow needs stronger reliability, monitoring, permissions, and support than one that exports an occasional report.

API usability also deserves explicit investigation. In a field study involving more than 440 professional developers, some of the most serious API-learning obstacles concerned documentation and other learning resources. Developers needed explanations of intent, code examples, links between scenarios and API features, and information they could navigate effectively. A technically complete interface may therefore remain commercially unusable if a new developer cannot quickly understand what it is for and complete a realistic task.

Partner and market evidence

Interview potential technology, implementation, referral, and marketplace partners separately from customers. Their incentives are different.

A credible partner assessment should establish:

• overlap between the companies’ target customers;
• the workflow or commercial problem the joint solution addresses;
• which party will build, certify, sell, implement, support, and update it;
• expected demand and how it was estimated;
• how each party benefits financially;
• access to technical contacts and test environments;
• marketplace, security, branding, and contractual requirements;
• dependence on another company’s API, policies, or pricing.

Partner enthusiasm is not evidence of partner capacity. Ask what similar integrations the partner currently maintains, who owns the relevant code, how support is staffed, how updates are tested, and what would cause the partner to stop investing.

A practical scoring model

Score each candidate against the same criteria. A five-point scale is usually sufficient because the purpose is to expose differences and assumptions, not to manufacture mathematical certainty.

The weights are a starting assumption, not an industry standard. A developer tool may place more weight on partner leverage and API quality. An enterprise product may give security, identity, audit, and data-residency requirements greater weight. A vertical product may prioritize one deep connection to the sector’s system of record over broad marketplace coverage.

Score confidence separately. A candidate with a high expected value but weak evidence should enter discovery, not automatically enter development.

The working goal of prioritizing a top five is useful because it forces choice while preserving a small portfolio of different opportunities. It is not a universal benchmark. A small team may be able to support only one or two new integrations. A mature platform may operate several parallel programmes. The number should reflect engineering capacity, partner readiness, support capacity, and the cost of maintaining what already exists.

A credible “top five” should therefore mean five investigated and ordered opportunities, not five promises to build at once.

Turn priorities into a buildable ecosystem plan

Once candidates have been ranked, choose the delivery model for each one. The company does not need to build every connection itself.

A roadmap may use five approaches.

A first-party integration is built and operated by the company. This is appropriate when the workflow is central to the product, the connection materially affects buying or retention, quality needs to be controlled closely, and expected adoption justifies continuing investment.

A partner-built integration is owned by another software company or specialist developer. This can add capability and distribution without placing all development work on the product team. It requires clear certification, support, data-access, change-management, and customer-ownership rules.

A public or partner API exposes product capabilities so multiple developers can build their own solutions. This is most useful when demand is varied, external developers have clear incentives, and the company can support a stable interface rather than a series of private exceptions.

An automation or integration platform connection uses an intermediary that already connects many products. It can test demand and cover lower-volume workflows faster than building each native connector. It may be unsuitable when transactions require complex data models, high throughput, low latency, extensive error recovery, or strict control of customer data.

A services-led connection is delivered for a particular customer through implementation work. This can be justified for high-value enterprise situations, but it should not be presented as a repeatable product integration until the common workflow and operating model have been demonstrated.

The decision flow should be simple enough for product, engineering, sales, partnerships, security, and support teams to use together.

flowchart TD
    A[Document the customer workflow] --> B{Repeated need in the target market?}
    B -->|No| C[Keep as customer-specific work or decline]
    B -->|Yes| D{Core to product value or risk?}
    D -->|Yes| E[Consider a first-party integration]
    D -->|No| F{Capable partner with aligned incentives?}
    F -->|Yes| G[Partner-built and certified integration]
    F -->|No| H{Can a standard API or automation platform serve it?}
    H -->|Yes| I[Enable through API or connector platform]
    H -->|No| J[Hold for further evidence]

In plain language: prove that the need repeats, decide whether the company must control the experience, look for a capable partner, and use a standard interface or intermediary where it can meet the requirement safely.

Define the whole product, not just the connector

Each roadmap item should include four work packages.

The customer experience covers discovery, authorization, configuration, field mapping, initial synchronization, error messages, disconnection, and support. It should specify the first useful outcome and how long a normal customer should need to reach it.

The technical contract covers supported objects and events, authentication, permissions, rate limits, webhooks, retries, duplicate handling, data ownership, logging, and service expectations. An OpenAPI description can provide a machine-readable and language-neutral account of an HTTP API’s operations and data structures, supporting documentation, testing, code generation, and other lifecycle activities.

The partner and commercial model covers ownership, development funding, marketplace fees, revenue sharing, lead registration, co-selling, customer communication, implementation, support escalation, and termination. Sales ownership must be explicit so that direct and partner teams do not compete for the same customer without rules.

The lifecycle plan covers testing, release, monitoring, changes, migration, and retirement. Research on boundary-resource management describes a lifecycle spanning planning and design, development and testing, release, maintenance and optimization, and deprecation. It also emphasizes that supporting materials—documentation, repositories, changelogs, tutorials, status information, and transition plans—must evolve with the technical interface.

This means every priority needs a named product owner, engineering owner, commercial owner, security reviewer, and support route. “The partner owns it” is not sufficient if customers believe they are buying an integrated solution from both companies.

Make security and change management entry conditions

A public or partner API enlarges the product’s operating boundary. It creates new authentication flows, data transfers, automated actions, dependencies, and potential abuse cases.

The Open Worldwide Application Security Project’s API guidance identifies recurring risks including broken authorization, broken authentication, unrestricted resource consumption, unsafe access to sensitive business flows, poor inventory management, and unsafe consumption of other APIs. NIST’s API protection guidance similarly treats security as a lifecycle issue, requiring risk identification and controls before and during operation rather than a review immediately before launch.

For delegated access, OAuth 2.0 is widely used, but implementing the label alone does not make a flow safe. The Internet Engineering Task Force’s current security guidance addresses redirect validation, token protection, authorization flows, and threats discovered through practical use of OAuth systems.

At minimum, the roadmap should not commit to external availability until the company can provide narrowly scoped permissions, separate test and production credentials, credential rotation and revocation, audit records, usage limits, incident handling, and an inventory of active clients and versions.

Change management is equally important. Stripe distinguishes backward-compatible monthly releases from major releases that may require integration changes. GitHub publishes breaking changes through dated API versions and states that an earlier REST API version will remain supported for at least 24 months after a newer version is released. These are company-specific policies, not rules every business must copy, but they illustrate the clarity developers need before investing in a dependency.

A smaller company may choose a different support period. It should still document what counts as a breaking change, how notice is delivered, how long overlapping versions will operate, how migrations are tested, and who pays the migration cost. The IETF’s Sunset response header also provides a standard way to indicate that an online resource is expected to become unavailable at a future date.

Large ecosystems show the value and the burden

Shopify’s App Store currently presents more than 16,000 apps and says each app passes a review containing 100 checkpoints. It also uses its “Built for Shopify” designation to identify apps that meet additional standards for performance, design, and integration.

The lesson is not that a growing software company should copy Shopify’s scale. It is that wider participation increases the need for discovery, quality signals, review, permissions, support standards, and enforcement. An open door without these controls can leave customers sorting through unreliable extensions and unclear ownership.

Atlassian similarly describes an ecosystem containing more than 7,000 Marketplace apps and more than 1,000 solution partners. Its Marketplace provides purchasing and licensing systems as well as distribution, while its development platform and policies govern what partners can build.

That ecosystem also illustrates lifecycle cost. Atlassian has announced plans to phase out support for its older Connect framework as it moves development toward Forge, requiring communication and migration work for customers and app developers. Its separate transition away from Data Center products also includes a multi-year schedule for winding down related Marketplace app sales.

The practical lesson is that an integration roadmap creates future obligations. Architecture changes that are sensible for the platform owner can impose substantial work on partners and customers. A company should assess not only whether it can launch an API, but whether it can maintain trust while changing it.

The risk also runs in the opposite direction when a product depends on somebody else’s API. In 2023, Reddit’s new API pricing and short implementation window led the developer of the popular Apollo client to announce that the application would close. The developer estimated that the proposed usage charges would cost about US$20 million annually at Apollo’s then-current request volume. The estimate came from the developer rather than an audited company disclosure, but the subsequent closure made the dependency risk concrete.

A roadmap that depends on an external platform should therefore record concentration risk: contractual rights, pricing exposure, rate-limit exposure, data-access restrictions, notice periods, substitute providers, and the effect on customers if access is withdrawn.

Measure integration influence without mistaking it for causation

The primary measure, integration influence, should show where an integration materially affects customer acquisition, activation, retention, or expansion. It should not be reduced to installation count.

An integration is “influential” when credible evidence indicates that it changed a decision or result. Examples include a buyer naming the connection as a purchase requirement, a customer completing onboarding through the integration, a partner introducing and assisting an opportunity, or an existing account adding users or products after enabling a connected workflow.

Use separate measures for different stages:

A basic sales measure can be written as:

Integration influence rate = qualified opportunities in which an integration was recorded as materially affecting the decision ÷ all qualified opportunities

Record the evidence and the stage at which influence was reported. A mandatory procurement requirement is stronger evidence than a sales representative selecting an “integration involved” checkbox after a win.

For existing customers, compare eligible connected and unconnected accounts, but do not assume the integration caused every difference. Larger and more sophisticated customers may both adopt more integrations and retain at higher rates. Segment by company size, plan, use case, tenure, and starting product adoption. A phased rollout, matched comparison, or controlled test can provide better evidence when sample sizes and operational conditions allow.

The metric should also deduct burden. An integration that influences substantial revenue but requires repeated custom mapping, senior engineering intervention, and high support effort may still be a poor scaling choice. Report influenced revenue beside build cost, implementation hours, failure rates, and ongoing maintenance cost.

The final evidence pack for each priority should contain:

1. a defined customer workflow and affected segment;
2. quantified sales, customer, and partner evidence;
3. a scored business case with confidence level;
4. the selected build and ownership model;
5. technical, security, support, and lifecycle requirements;
6. expected measures and a review date;
7. a clear decision: commit, discover further, enable through a partner, or decline.

The top-five roadmap is complete when these decisions are comparable and resources can be allocated—not when five vendor names have been placed on a slide.

Know what must be true before depending on the roadmap

Integration work often looks complete before it is operationally ready.

The most common superficial result is a ranked list based on sales votes. This favours the loudest current opportunity, does not distinguish target customers from weak-fit prospects, and ignores maintenance cost.

Another is a catalogue of endpoints presented as an API product. If developers lack a test environment, realistic examples, usable permissions, monitoring, versioning, and support, the company has transferred internal complexity to its partners rather than enabled them.

A third is an unsigned partnership announcement. A logo exchange or marketplace listing does not establish demand, technical ownership, lead flow, implementation capacity, or support obligations.

A fourth is counting all revenue from connected customers as integration influence. That overstates value and makes it impossible to distinguish mandatory workflow connections from integrations installed after the customer had already committed.

A fifth is leaving retirement out of the roadmap. Every new connector creates future work when either product changes. Version support, migrations, security fixes, partner exits, and customer communication are part of the cost from the beginning.

There are also situations in which the usual recommendation to build integrations should not apply.

A company should wait when its core data model changes frequently, permissions are unreliable, onboarding still requires major founder intervention, or support cannot diagnose synchronization failures. It should also hesitate when requests come mainly from non-target customers, when a standard export is sufficient, or when the proposed partner cannot demonstrate demand and maintenance capacity.

Conversely, one integration may deserve priority even with limited request volume when it is a non-negotiable part of a clearly chosen market. A healthcare, financial, public-sector, or sector-specific product may need a deep connection to an identity provider, regulated record system, or industry platform before its addressable customers can use it safely. This is a judgment about the chosen market, not a popularity score.

Before the company depends on integrations as a sales or partner channel, the following should be true:

The core product and onboarding process work without routine rescue. The target customer and important workflows are understood. Sales records integration requirements consistently. The API and connectors have named owners. Security, monitoring, versioning, and support are designed into the service. Partners know how they will create and capture value. Channel ownership rules prevent avoidable conflict. Management can distinguish installations from active use and influence from attribution.

At that point, the roadmap supports a real decision: which connections deserve scarce product capacity, which should be enabled through partners or standard interfaces, and which should not be built.

The result is not the largest possible integration catalogue. It is a small, defensible portfolio that removes meaningful friction, strengthens customer workflows, and creates leverage the business can continue to support.

Sources

Primary and official sources

• OpenAPI Initiative, What Is OpenAPI? and OpenAPI Specification.
• NIST, Guidelines for API Protection for Cloud-Native Systems.
• Open Worldwide Application Security Project, API Security Top 10 — 2023.
• Internet Engineering Task Force, Best Current Practice for OAuth 2.0 Security and The Sunset HTTP Header Field.
• Stripe, API Versioning.
• GitHub, REST API Breaking Changes and Version Support.
• Shopify, Shopify App Store.
• Atlassian, Atlassian Ecosystem, Marketplace Documentation, and platform-transition announcements.

Open research

• Engert et al., The Engagement of Complementors and the Role of Platform Boundary Resources in E-Commerce Platform Ecosystems.
• Wulfert, Boundary Resource Management in Innovation Ecosystems: The Case of E-Commerce.
• Robillard and DeLine, A Field Study of API Learning Obstacles.

Public reporting

• Ars Technica and TechCrunch reporting on Reddit’s 2023 API-pricing changes and the closure of Apollo.