Markdown Editor

Integration Strategy Template (EIP, AsyncAPI 3.1, OpenAPI 3.2)

Drivers, landscape and debt, principles, style decision tree, system/process/experience layers, platform scoring, canonical policy, CoE RACI, roadmap, KPIs

АрхітектураПовнийEnterprise Integration Patterns (names); AsyncAPI 3.1.0; CloudEvents 1.0.2; OpenAPI 3.2integrationstrategy

Як використовувати: Use it when an organisation needs one set of integration rules, platforms and ownership that every project inherits. Fill the drivers and the current landscape with its integration debt first, then the style decision tree and the platform decision. The main pitfall is allowing every style and platform everywhere, which recreates the sprawl the strategy is meant to remove.

Перегляд

Integration Strategy: [Organisation name]

Enterprise-level strategy for how applications, data, partners and people are connected: business drivers, the current integration landscape and its debt, integration principles, the styles the organisation uses (synchronous API, events, batch and file, B2B and EDI, data replication), a layered API model, the integration platform decision (iPaaS, enterprise service bus, event broker, API gateway, managed file transfer), canonical model policy, reuse and catalogue, security, operating model and centre of excellence, funding, roadmap and KPIs. Patterns are named with the vocabulary of Enterprise Integration Patterns (Hohpe and Woolf, 2003); asynchronous contracts follow AsyncAPI 3.1.0 and CloudEvents 1.0.2, synchronous contracts follow the OpenAPI Specification 3.2. Replace every [bracketed] value and every row marked Example.

Document control

FieldValue
Document ID[INT-STRAT-001]
Organisation or business unit[Name]
Planning horizon[YYYY to YYYY]
Version[0.1]
Status[Draft / In review / Approved / Superseded]
Owner[@head-of-integration]
Approvers/reviewers[@chief-architect], [@ciso], [@cfo-delegate], [@head-of-applications]
Classification[Internal / Confidential]
Last updatedYYYY-MM-DD
Review cycle[Yearly, or on a major platform change]
Related documents[Enterprise architecture vision], [Application portfolio], [Data strategy]

Approvals

RoleNameDecisionDate
Chief architect[@name][Approve / Approve with conditions / Reject]YYYY-MM-DD
Chief information security officer[@name][Decision]YYYY-MM-DD
Head of applications[@name][Decision]YYYY-MM-DD
Finance[@name][Decision]YYYY-MM-DD
Architecture board[@name][Decision]YYYY-MM-DD

Revision history

VersionDateAuthorChange summary
0.1YYYY-MM-DD[@name]First draft
1.0YYYY-MM-DD[@name]Example: Approved; iPaaS plus event broker chosen, ESB retirement planned
1.1YYYY-MM-DD[@name]Example: Added B2B style rules after EDI provider review

Contents

1. Purpose, scope and drivers

1.1 Purpose

This strategy sets how [Organisation name] connects its applications, data, partners and channels for the planning horizon. It tells project teams which integration styles to use, which platforms to build on, which contracts and standards to follow, who owns what, and how integration work is funded. It replaces ad hoc, project-by-project integration choices with a small set of governed options.

1.2 Scope

In scopeOut of scope
Example: All application-to-application, application-to-partner and channel-to-backend integrationAnalytics pipelines inside the data platform (see Data Platform Architecture, architecture/data-platform-architecture)
Example: Integration platforms, contracts, security, operating model and fundingNetwork connectivity and firewall design
Example: B2B and EDI with suppliers, carriers and marketplacesRobotic process automation of user interfaces
[Item][Item]

1.3 Business drivers

IDDriverEvidenceIntegration implication
DRV-001 (Example)Launch new sales channels in weeks, not quartersLast two channels took 7 and 9 months, 60 % of effort was integrationReusable product, price and stock APIs; self-service onboarding
DRV-002 (Example)Real-time stock visibility across stores and onlineOverselling incidents during peak; nightly batch stock feedEvent-based stock updates with seconds of latency
DRV-003 (Example)ERP replacement planned in two yearsERP vendor end of mainstream supportDecouple consumers from the ERP behind stable system APIs
DRV-004 (Example)Onboard 200 more suppliers with less manual workOnboarding takes 6 weeks per partnerPartner self-service, standard EDI maps, test automation
DRV-005 (Example)Reduce integration run costTwo overlapping platforms and a legacy ESB licencePlatform consolidation
[DRV-NNN][Driver][Evidence][Implication]

2. Current integration landscape

2.1 Interface inventory

StyleCountPlatform todayShare of incidentsComment
Synchronous API (REST, SOAP) (Example)140Custom code, legacy ESB35 %No common gateway; credentials embedded in code
Events and messaging (Example)25Queue product on premises10 %Point-to-point queues, no schema governance
Batch and file (Example)210Scheduler and SFTP scripts40 %Failures found next morning
B2B and EDI (Example)120 partnersOutsourced EDI provider10 %Maps owned by provider
Database links and shared tables (Example)18Direct5 %Block ERP upgrade
[Style][Count][Platform][Share][Comment]

2.2 Integration debt

IDDebt itemConsequenceEstimated yearly costLinked driver
DEBT-001 (Example)18 direct database links into the ERPERP cannot be upgraded or replaced without breaking consumers[USD 400,000 in rework risk]DRV-003
DEBT-002 (Example)No central monitoring for file transfersLate detection, manual reruns[USD 150,000 in support effort]DRV-002
DEBT-003 (Example)Legacy ESB on unsupported versionSecurity exposure, scarce skills[USD 250,000 licence and support]DRV-005
[DEBT-NNN][Item][Consequence][Cost][DRV-NNN]

3. Integration principles

IDPrincipleRationaleConsequence for projects
INP-001 (Example)No consumer integrates directly with another application's databaseShared schemas freeze both sidesDatabase links are forbidden for new work; existing ones are on the retirement roadmap
INP-002 (Example)Publish business events for every significant state change of a core entityConsumers react without polling; producers stay unaware of consumersCore systems emit events through the outbox or CDC (section 4)
INP-003 (Example)Every interface has a machine-readable contract under version controlContracts enable testing, catalogue and change controlOpenAPI for HTTP, AsyncAPI for events, schema files for batch and EDI maps
INP-004 (Example)Reuse before build: check the catalogue firstDuplicate interfaces multiply run costDesign review asks for the catalogue search result
INP-005 (Example)Integration logic is thin; business rules live in the owning applicationLogic in middleware becomes an unowned second systemOrchestration only when it spans several owners (process layer, section 5)
INP-006 (Example)Asynchronous by default across domain boundaries, synchronous where a caller needs an immediate answerLimits coupling of availabilityStyle decision tree in section 4.2
INP-007 (Example)Secure every interface by default with authenticated, encrypted transportInternal networks are not trustedZero trust rules in section 11
INP-008 (Example)Observable end to end: every message carries a correlation identifierFault finding across hopsTrace context propagated through all platforms
[INP-NNN][Principle][Rationale][Consequence]

4. Integration styles and selection

4.1 Supported styles

StyleUse whenAvoid whenContract standardDefault platform
Synchronous request and response APIA caller needs an answer now (query, validation, command with immediate result)The callee is slow, often unavailable, or the caller does not need the answerOpenAPI 3.2API gateway plus iPaaS or service runtime
Event notification and event-carried state transferMany consumers need to know that something happened; producers must not depend on consumersA reply is required in the same interactionAsyncAPI 3.1.0 with CloudEvents 1.0.2 envelopeEvent broker
Asynchronous command (queue)One known receiver must do work reliably and at its own paceSeveral independent consumers need the same factAsyncAPI 3.1.0Message queue on the event broker
Batch and fileLarge volumes, period-end processing, systems that only accept filesLatency below [15 minutes] is neededFile layout specification with schemaManaged file transfer and scheduler
B2B and EDIExternal trading partners using X12, EDIFACT or industry XMLPartner offers a modern API that meets the needStandard message plus partner implementation guideB2B gateway or EDI provider
Data replication and change data captureCopying data sets for read models, search or analyticsCross-domain business processes (use events instead)Change event schemaCDC tooling to the event broker
[Style][Use when][Avoid when][Contract][Platform]

4.2 Style decision tree

Record any departure from the tree as an exception in the design review with the reason and an expiry date.

4.3 Getting events out of core systems

Core applications that cannot publish events natively use one of two approved techniques. The transactional outbox pattern writes the business change and the outgoing message in the same local transaction; a relay then publishes the message, so an event is emitted only when the change commits. Log-based change data capture reads the database transaction log and turns committed changes into change events; it needs no application change but exposes table structure, so a translation step must turn row changes into business events before they leave the owning domain. System Design: CDC Pipeline (system-design/design-cdc-pipeline) covers the mechanics.

5. Layered API model

LayerPurposeOwned byChange rateRules
SystemExpose one system of record in a stable, cleaned-up contract that hides its internalsTeam that owns the applicationLowOne system API per system and entity; no business orchestration; shields consumers from replacement of the system
ProcessCombine system APIs and events into a business capability used by several channelsDomain or capability teamMediumOwns orchestration and cross-system rules; no channel-specific formatting
ExperienceShape data for one channel or consumer groupChannel teamHighMay aggregate, filter and paginate for its client; no direct call to system APIs unless an exception is approved under section 5.1

5.1 When to skip a layer

SituationAllowed shortcutCondition
Example: Single consumer, simple read of one systemExperience calls system API directlyLogged as an exception; revisited when a second consumer appears
Example: Internal batch jobNo experience layerJob uses process or system API
Example: Event-driven flowLayers apply to request and response only; events follow section 4Event producers are owners of the system of record
[Situation][Shortcut][Condition]

6. Pattern vocabulary

The organisation uses the pattern names catalogued at enterpriseintegrationpatterns.com. The table lists the patterns that designs must name explicitly and the house rule for each.

Pattern (EIP name)House rule
Publish-Subscribe ChannelDefault channel type for business events; one topic per event family
Point-to-Point ChannelUsed for asynchronous commands to one receiver
Guaranteed DeliveryRequired for all business events and commands; brokers persist messages before acknowledging
Dead Letter ChannelEvery consumer has one; alerts fire on first arrival
Idempotent ReceiverEvery consumer of at-least-once channels deduplicates on event ID
Correlation IdentifierEvery message and API call carries a correlation ID propagated end to end
Content-Based RouterAllowed in the process layer; routing rules are versioned with the flow
Message Translator and NormalizerMapping to and from canonical or partner formats lives at the edge of the platform
Canonical Data ModelApplied per domain only, see section 9
Claim CheckPayloads above [256 KB] are stored in object storage and referenced by URI
Aggregator, Splitter, ResequencerAllowed in process flows with explicit timeout and completion rules
Process ManagerLong-running orchestration only on the approved workflow runtime
Wire Tap and Message StoreUsed for audit and replay; subject to retention rules in section 11
Competing ConsumersStandard scaling technique for queues

7. Platform capabilities and options

7.1 Required capabilities

IDCapabilityNeeded by stylesPriority
CAP-001 (Example)API gateway with policy enforcement, quotas and analyticsSynchronous APIMust
CAP-002 (Example)Developer portal and API catalogueSynchronous API, eventsMust
CAP-003 (Example)Low-code integration flows with connectors to SaaS and ERPSynchronous API, batchMust
CAP-004 (Example)Durable event broker with retention and replayEvents, commands, CDCMust
CAP-005 (Example)Schema registry with compatibility checksEventsMust
CAP-006 (Example)Managed file transfer with scheduling, checksums and auditBatch and fileMust
CAP-007 (Example)B2B gateway: AS2, AS4, SFTP, EDI translation, partner managementB2B and EDIShould
CAP-008 (Example)End-to-end monitoring, tracing and business activity viewsAllMust
CAP-009 (Example)Hybrid runtime that can run close to on-premises systemsAllShould
[CAP-NNN][Capability][Styles][Must / Should / Could]

7.2 Platform categories

CategoryStrengthsWeaknessesTypical fit
Integration platform as a service (iPaaS)Connectors, low-code flows, managed runtime, fast deliveryPer-flow or per-message cost; vendor lock-in of flow definitionsSaaS-heavy estates, process and system APIs
Enterprise service bus (on-premises)Mature transformation and routing, existing skillsCentral bottleneck team, scaling and upgrade costLegacy estates, being retired in many organisations
Event broker or streaming platformHigh throughput, decoupling, replayNeeds schema and topic governance; not a transformation engineEvents, CDC, streaming
API gateway and managementSecurity, quotas, portal, analytics at the edgeNot suited to orchestration or heavy mappingAll exposed APIs
Managed file transferReliable, audited file movement, schedulingBatch latencyFiles and bulk data
B2B gateway or managed EDI servicePartner protocols, EDI standards, onboarding servicesSpecialist skills, per-partner costTrading partners
Code-based integration on a service platformFull control, testable code, no licenceNeeds engineering capacity and shared librariesComplex domain logic, high scale

8. Platform decision

CriterionWeightOption A: iPaaS + managed brokerOption B: refresh ESB + brokerOption C: code-based on service platform
Capability coverage (CAP-001 to CAP-009) (Example)30 %433
Delivery speed for new integrations (Example)20 %532
Five-year total cost (Example)20 %324
Skills availability (Example)10 %423
Hybrid and data residency fit (Example)10 %345
Exit cost and portability (Example)10 %225
Weighted score (Example)100 %3.702.703.40

Scores use 1 (poor) to 5 (excellent). The weighted score for option A is 0.3 x 4 + 0.2 x 5 + 0.2 x 3 + 0.1 x 4 + 0.1 x 3 + 0.1 x 2 = 3.70, option B scores 2.70 and option C 3.40. Recompute every row when you replace the example scores.

DecisionChoiceADR
Example: Integration runtimeOption A, iPaaS for flows and system APIsADR-INT-001
Example: Event brokerManaged streaming service in the primary cloud regionADR-INT-002
Example: B2BKeep outsourced EDI provider for two years, then reviewADR-INT-003
Example: Legacy ESBRetire by YYYY-MM; no new interfaces from YYYY-MM-DDADR-INT-004
[Decision][Choice][ADR-ID]

9. Canonical data and contract policy

Policy areaRule
Scope of canonical modelsExample: One canonical model per business domain (product, customer, order, stock); no single enterprise-wide model
OwnershipExample: The domain team that owns the system of record owns the canonical model; changes go through its contract review
Mapping locationExample: Translate at the edge: system APIs map system formats to the domain model; partners are mapped in the B2B gateway
IdentifiersExample: Global identifiers issued by the system of record or the master data hub (Master Data Management Design, architecture/master-data-management-design)
Reference dataExample: Country, currency and unit codes follow ISO code lists; local codes are mapped, not exposed
VersioningExample: Semantic versioning on every contract; breaking changes need a new major version and a deprecation period (API Deprecation Policy, architecture/api-deprecation-policy)
Data contracts for analyticsExample: Datasets published to the data platform use a data contract (ai-data/data-contract)
Personal dataExample: Contracts mark personal data fields; minimise fields per consumer

10. Reuse, catalogue and lifecycle

10.1 Catalogue content

Every interface, API, event type and file feed is registered with: ID, name, owner, style, contract link, version, lifecycle state, data classification, consumers, service level and support channel. The developer portal (API Management Platform Design, architecture/api-management-platform-design) and the event catalogue (Event-Driven Architecture Design, architecture/event-driven-architecture-design) are the user-facing views of the same register.

10.2 Lifecycle states

An interface moves through five states; only Published interfaces may gain new consumers.

10.3 Reuse rules

RuleCheck
Example: Search the catalogue before proposing a new interfaceDesign review records the search and why existing interfaces do not fit
Example: Extending an existing contract is preferred over creating a parallel oneBackward-compatible additions only
Example: Interfaces with no consumer for 6 months are candidates for retirementQuarterly catalogue review
[Rule][Check]

11. Security and identity

AreaBaseline rule
TransportTLS 1.2 or later on every hop, TLS 1.3 preferred; mutual TLS for service-to-service traffic between trust zones
API authenticationOAuth 2.0 client credentials or token exchange for machine callers, following the OAuth 2.0 Security Best Current Practice (RFC 9700, January 2025); API keys only for low-risk public data and never alone for write access
User delegationAuthorisation code flow with PKCE through the corporate identity provider
Financial-grade APIsWhere open banking or high-value payments apply, follow the FAPI 2.0 Security Profile (OpenID Foundation, Final, February 2025); see Open Banking API Design (industry/open-banking-api-design)
Event brokerPer-client identities, topic-level access control lists, no shared credentials
Files and B2BKey-based SFTP or certificate-based AS2 and AS4 with signed receipts; keys rotated per section 9 of the B2B, EDI and File Transfer Design
SecretsHeld in the secrets manager; no credentials in flow definitions or code
Data protectionField-level encryption or tokenisation for card and special-category data; personal data minimised per consumer
LoggingPayload logging off by default for classified data; audit events retained [13 months]
Threat modellingRequired for every externally exposed interface (security/threat-model)

12. Operating model and centre of excellence

12.1 Model choice

ModelDescriptionUse when
CentralisedOne integration team designs, builds and runs all interfacesSmall estate or low maturity
Federated with centre of excellencePlatform team runs the platforms; domain teams build; the centre of excellence sets standards and reviewsMedium to large estates with capable domain teams
Fully decentralisedTeams choose and run their own toolsRarely appropriate for shared integration

Example: The organisation adopts the federated model with a centre of excellence of [6] people (lead architect, two platform engineers, an API product manager, a B2B specialist and an enablement lead).

12.2 RACI

ActivityCentre of excellencePlatform teamDomain teamSecurityArchitecture board
Integration standards and patternsA, RCCCI
Platform operation and upgradesCA, RICI
Interface designCIA, RCI
Interface build and testICA, RII
Contract review for shared APIs and eventsA, RIRCI
Exceptions to this strategyRCCCA
Partner onboarding (B2B)A, RRCCI

12.3 Enablement

ItemDescription
Example: Starter templatesFlow, API and event templates with logging, security and error handling built in
Example: Training pathPlatform basics, API design, event design, security, two-day bootcamp per quarter
[Item][Description]

13. Funding and chargeback

Cost elementFunding approachAllocation key
Platform licences and infrastructure (Example)Central IT budget for the base; showback to domainsMessage volume or API calls per domain
Centre of excellence staff (Example)Central budgetNot charged
Interface build (Example)Project budget of the first consumerNot shared
Reusable system API build (Example)Central reuse fund up to [USD 50,000] per APIRepaid through later consumer fees, if any
B2B partner onboarding (Example)Business unit that requests the partnerPer partner
[Element][Approach][Key]

14. Roadmap and traceability

14.1 Transition states

PhaseWindowOutcomesExit criteria
Foundation (Example)Q1 to Q2 YYYYGateway, iPaaS, broker and schema registry live; standards publishedFirst three interfaces in production on new platforms
Decouple the ERP (Example)Q3 YYYY to Q2 YYYYSystem APIs and events for product, stock, order, customerDatabase links reduced from 18 to 4
Retire legacy ESB (Example)Q3 to Q4 YYYYAll ESB interfaces migratedESB decommissioned, licence ended
B2B modernisation (Example)YYYYPartner self-service onboarding, AS4 optionOnboarding time below 2 weeks
[Phase][Window][Outcomes][Exit criteria]

14.2 Migration rules for existing interfaces

RuleDetail
Example: Migrate on changeAny interface touched by a project moves to the target platform in that project
Example: Migrate by riskInterfaces with the highest incident share migrate first
Example: FreezeNo new interface on the legacy ESB from YYYY-MM-DD
[Rule][Detail]

14.3 Traceability matrix

Driver or debtPrinciplesCapabilitiesRoadmap phaseKPI
DRV-001 (Example)INP-003, INP-004CAP-001, CAP-002, CAP-003FoundationKPI-001
DRV-002 (Example)INP-002, INP-006CAP-004, CAP-005Decouple the ERPKPI-003
DRV-003 / DEBT-001 (Example)INP-001CAP-003Decouple the ERPKPI-004
DRV-004 (Example)INP-003CAP-007B2B modernisationKPI-005
DRV-005 / DEBT-003 (Example)INP-004CAP-003Retire legacy ESBKPI-006
[ID][INP-NNN][CAP-NNN][Phase][KPI-NNN]

15. KPIs and measures

IDKPIBaselineTargetSource
KPI-001 (Example)Lead time from request to production for a new integration10 weeks3 weeksDelivery tracker
KPI-002 (Example)Reuse ratio: consumers per published API or event type1.12.5Catalogue
KPI-003 (Example)Stock update latency from WMS to channels, 95th percentile12 hours30 secondsBroker metrics
KPI-004 (Example)Direct database links into the ERP180Interface inventory
KPI-005 (Example)Partner onboarding time6 weeks2 weeksB2B gateway
KPI-006 (Example)Integration platform run cost per year[USD 1.2 million][USD 0.8 million]Finance
KPI-007 (Example)Integration incidents per month with business impact144Incident tool
[KPI-NNN][KPI][Baseline][Target][Source]

16. Risks, assumptions and decisions

IDTypeDescriptionResponseOwner
RSK-001 (Example)RiskDomain teams lack integration skills for the federated modelEnablement plan, centre of excellence pairing for first two projects@coe-lead
RSK-002 (Example)RiskiPaaS cost grows faster than usage forecastMonthly cost review, quotas per domain@finops-lead
RSK-003 (Example)RiskEvent broker becomes a dumping ground for unowned topicsTopic ownership and catalogue rules, see EDA design@eda-lead
ASM-001 (Example)AssumptionERP vendor supports outbox or CDC for core tablesProof of concept in Foundation phase@erp-architect
DEC-001 (Example)DecisionDomain canonical models, not an enterprise modelADR-INT-005@chief-architect
[ID][Risk / Assumption / Decision][Description][Response][@owner]

17. Glossary and references

17.1 Glossary

TermMeaning
iPaaSIntegration platform delivered as a managed cloud service
ESBEnterprise service bus, a central middleware for routing and transformation
System, process, experience APILayers of the layered API model in section 5
Canonical data modelShared message format that several applications map to
OutboxTable written in the same transaction as the business change, read by a relay that publishes messages
CDCChange data capture from a database log
MFTManaged file transfer
Centre of excellenceSmall team that owns integration standards, platforms and enablement

17.2 References

ReferenceVersion or date checkedUse
Enterprise Integration Patterns, Gregor Hohpe and Bobby Woolf, Addison-Wesley, and enterpriseintegrationpatterns.comBook 2003; site checked YYYY-MM-DDPattern names in section 6
AsyncAPI Specification, asyncapi.com3.1.0 (January 2026)Event and message contracts
CloudEvents, CNCF, github.com/cloudevents/spec1.0.2Event envelope
OpenAPI Specification, spec.openapis.org3.2 (3.2.0 September 2025, 3.2.1 September 2026)HTTP API contracts
RFC 9700, Best Current Practice for OAuth 2.0 Security (BCP 240), IETFJanuary 2025Section 11
FAPI 2.0 Security Profile, OpenID FoundationFinal, February 2025Financial-grade APIs
Transactional outbox pattern, microservices.io (Chris Richardson)Checked YYYY-MM-DDSection 4.3
API-led connectivity, MuleSoftVendor concept, checked YYYY-MM-DDLayer names in section 5
[Internal standard][Version][Use]

Standard and licence note

Based on public specifications: AsyncAPI 3.1.0 (Linux Foundation, Apache 2.0), CloudEvents 1.0.2 (CNCF, Apache 2.0), the OpenAPI Specification 3.2, RFC 9700 and the FAPI 2.0 Security Profile. Pattern names come from Enterprise Integration Patterns by Gregor Hohpe and Bobby Woolf; the site publishes pattern names, icons and summaries under CC BY 4.0, and this template uses the names only, with attribution, and writes all explanations in original words. The system, process and experience layering is described in neutral terms; "API-led connectivity" is a term used by MuleSoft, a trademark of its owner, and this template is not affiliated with or endorsed by any vendor. This template is original text written for this collection. Check the current official version of every specification before use. Template licence: MIT.

Схожі шаблони