How to Design an API-Led Connectivity Architecture from Scratch.

Point-to-point integrations look like the fast path. They are not. They are technical debt in disguise. Every new system added means a new direct connection, duplicated logic, and a growing tangle that no one wants to own when it breaks. The economics are brutal: a landscape of N systems produces up to N(N-1)/2 direct connections. At 20 systems, that is potentially 190 bespoke pipelines. Add a version upgrade to any one of them and you are rewriting integrations, not delivering features.

API-led connectivity reorganises integration around layered, reusable APIs rather than direct system connections. Each layer has a defined role, a defined consumer, and a defined change cadence. Integration assets become discoverable, versioned, and independently maintainable.

When to use this pattern: use API-led connectivity when your integration landscape has five or more systems, multiple consuming channels (web, mobile, partner, back-office), or a requirement for reusable business capabilities across teams. For single-system, single-consumer integrations, the three-layer overhead is not justified.

The three-layer model

Prerequisites

Step 1: Map your systems of record

Before writing a single API specification, build a complete inventory of every system that owns data in your landscape. The inventory directly determines your System API surface: one System API per system of record. Ambiguities in the inventory become architectural ambiguities later, at a much higher cost to fix.

For each system, capture at minimum: name, domain, supported operations, authentication mechanism, p95 latency, throughput, hosting model, and the System API candidate name. Pay particular attention to ownership: a system that appears in multiple business domains may need separate System APIs per domain to maintain clean layer boundaries.

Inventory template

Store this JSON structure in source control alongside your API specifications.

{
  "systems": [
    {
      "name": "Salesforce CRM",
      "domain": "customer",
      "operations": ["query", "create", "update", "upsert"],
      "auth": "OAuth 2.0 (connected app, client credentials)",
      "latency_p95_ms": 400,
      "throughput_rps": 50,
      "hosted": "cloud",
      "system_api_candidate": "customer-system-api"
    },
    {
      "name": "SAP ERP S/4HANA",
      "domain": "finance",
      "operations": ["query", "post", "idoc-inbound"],
      "auth": "basic (service user)",
      "latency_p95_ms": 1200,
      "throughput_rps": 10,
      "hosted": "on-premises",
      "system_api_candidate": "finance-system-api"
    }
  ]
}

Step 2: Design System APIs first

Start with RAML 1.0 or OpenAPI 3.0 specifications before any implementation. The spec is the contract. A spec written after the implementation reflects the implementation, not the design intention.

Publish every specification to Anypoint Exchange before the first line of implementation code is written. Publishing early enables parallel design work across teams and surfaces contract conflicts at design time, not at integration time.

Each System API specification must define: a versioned base URI, canonical data types (never pass-through system schemas), a RESTful resource structure, standardised error responses, and security schemes.

RAML 1.0 System API specification structure

#%RAML 1.0
title: Customer System API
version: v1
baseUri: /api/v1
mediaType: application/json

securitySchemes:
  oauth_2_0: !include security/oauth2.raml

types:
  Customer:
    type: object
    properties:
      id:          { type: string, description: "UUID v4. Enterprise canonical identifier." }
      externalRef: { type: string, required: false, description: "Source system ref (e.g. SF-XXXXXXX)" }
      firstName:   string
      lastName:    string
      email:       { type: string, pattern: "^[^@\s]+@[^@\s]+\.[^@\s]+$" }
      createdAt:   datetime

/customers:
  get:
    securedBy: [oauth_2_0]
    queryParameters:
      email?:     string
      tenantId?:  string
    responses:
      200: { body: { type: Customer[] } }
  post:
    securedBy: [oauth_2_0]
    body:
      { type: Customer }
    responses:
      201: { body: { type: Customer } }
      400: { body: { type: !include types/ErrorResponse.raml } }
  /{id}:
    get:
      responses:
        200: { body: { type: Customer } }
        404: { body: { type: !include types/ErrorResponse.raml } }

Step 3: Design Process APIs around business capabilities

Map your business capabilities first: customer lifecycle, order fulfilment, billing and collections, inventory management. These become your Process API candidates. The common mistake is to start from the systems you have and derive Process APIs from them. That produces APIs named sap-connector and salesforce-bridge, which encode implementation decisions in the API contract and become liabilities the moment the underlying system changes.

Every Process API name must describe what the business does, not which system it touches. Customer onboarding. Order management. Invoice processing. These names remain stable even if the underlying systems are replaced. That stability is precisely the point.

Process API flow skeleton

<flow name="customer-onboarding-main-flow">
  <http:listener config-ref="HTTP_Listener_Config"
    path="/v1/customers/onboard" method="POST"
    doc:name="POST /v1/customers/onboard"/>

  <flow-ref name="validate-onboarding-payload-subflow"/>

  <!-- Create canonical customer record via System API -->
  <http:request config-ref="CustomerSystemAPI_Config"
    path="/v1/customers" method="POST"
    doc:name="Create customer (System API)"/>
  <set-variable variableName="customerId"
    value="#[payload.id]" doc:name="Store customerId"/>

  <!-- Provision CRM account via System API -->
  <http:request config-ref="CRMSystemAPI_Config"
    path="/v1/accounts" method="POST"
    doc:name="Create CRM account (System API)"/>

  <!-- Assemble composite response -->
  <ee:transform doc:name="Build onboarding response">
    <ee:message>
      <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
  customerId:    vars.customerId,
  crmAccountId:  payload.id,
  status:        "ONBOARDED",
  onboardedAt:   now() as String { format: "yyyy-MM-dd'T'HH:mm:ssZ" }
}]]></ee:set-payload>
    </ee:message>
  </ee:transform>
</flow>

Step 4: Design Experience APIs for each consumer type

Start every Experience API design with a consumer contract, not a data model. Understand the exact payload shape the consumer needs, the performance requirements (p95 response time), the security model, and the versioning expectations before writing a single RAML type.

An Experience API is tailored, not generic. A mobile Experience API and a partner portal Experience API may both call the same Order Management Process API, but they return different payload shapes, use different authentication schemes, and enforce different SLA policies.

Key design considerations: payload shaping (filter, flatten, or aggregate Process API responses); authentication model (OAuth 2.0 client credentials for partners, OAuth 2.0 authorisation code for end-user apps, mTLS for internal high-security consumers); SLA tiers (bronze, silver, gold registered as client applications in Anypoint API Manager); and response caching for read-heavy, low-churn data.

DataWeave payload shaping

The following transformation shapes a Process API order response into a lightweight mobile consumer payload, stripping back-office fields and pre-computing the order total.

%dw 2.0
output application/json
---
{
  orderId:           payload.id,
  statusLabel:       payload.status match {
    case "PENDING_PAYMENT" -> "Awaiting payment"
    case "PROCESSING"      -> "Being prepared"
    case "SHIPPED"         -> "On the way"
    else                   -> payload.status
  },
  totalAmount:       payload.lines reduce (
    (item, acc = 0.00) -> acc + (item.unitPrice * item.quantity)
  ),
  currency:          payload.currency default "USD",
  estimatedDelivery: payload.shipping.estimatedDate,
  lineCount:         sizeOf(payload.lines)
}

Step 5: Choose the right data model for each layer

Data modelling in an API-led architecture is a strategic decision that most teams treat as an implementation detail. The data model chosen at each layer determines how much coupling is introduced, how easily the architecture can evolve, and how much transformation work the integration layer carries per request.

The three model options

Defining an EDM type in RAML

Store EDM types as a shared RAML library published to Anypoint Exchange. All System and Process APIs import from this library. This is the mechanism that enforces canonical field names across the organisation.

# Published to Exchange as: com.myorg:enterprise-data-model:1.0.0
#%RAML 1.0 Library
types:
  Customer:
    description: |
      Enterprise-canonical customer record.
      All System APIs returning customer data must conform to this type.
    type: object
    properties:
      id:
        type: string
        description: "UUID v4. Enterprise canonical identifier."
        pattern: "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      externalRef:
        type: string
        required: false
        description: "Source system native key (e.g. SF-003XXXXXXX, SAP-KUNNR)"
      firstName:   string
      lastName:    string
      email:
        type: string
        pattern: "^[^@\s]+@[^@\s]+\.[^@\s]+$"
      tenantId:    string
      createdAt:   datetime
      updatedAt:   datetime

Step 6: Govern and secure the architecture

An API-led architecture without governance produces a different kind of sprawl: API spaghetti instead of integration spaghetti. Governance requires decisions at design time (naming standards, data model conventions, versioning policy), enforcement at deployment time (API Manager policies, autodiscovery), and visibility at runtime (structured logging, Anypoint Monitoring, correlation IDs).

Apply policies through API Manager

Every API deployed to the platform must be registered in Anypoint API Manager. Use API Autodiscovery to link the running Mule application to its API Manager definition. Without autodiscovery, policies are defined but never enforced at runtime.

<!-- global-config.xml: register with Anypoint API Manager via autodiscovery -->
<api-gateway:autodiscovery apiId="${api.id}"
  flowRef="customer-experience-api-main"
  doc:name="API Autodiscovery"/>

<!-- Apply policies declaratively in API Manager (not in code):
  - OAuth 2.0 Token Enforcement     (Experience layer only)
  - Rate Limiting SLA-Based         (Experience layer only)
  - JSON Threat Protection          (Experience layer only)
  - Client ID Enforcement           (all layers)
  - Spike Control                   (System layer, to protect backend)
-->

Security model by layer

Observability: correlation ID propagation

Instrument every API layer with structured JSON logging. Generate a correlation ID at the Experience layer and propagate it through every downstream call via a custom HTTP header (X-Correlation-Id). This is the minimum required to diagnose cross-layer failures in production.

<!-- Set correlation ID at Experience API entry point -->
<set-variable variableName="correlationId"
  value="#[correlationId default uuid()]"
  doc:name="Set correlationId"/>
<set-variable variableName="clientId"
  value="#[attributes.headers['client_id'] default 'unknown']"
  doc:name="Set clientId"/>

<!-- Propagate to downstream Process / System API calls -->
<http:request config-ref="ProcessAPI_Config"
  path="/v1/customers/onboard" method="POST">
  <http:headers><![CDATA[#[{
    "X-Correlation-Id": vars.correlationId,
    "X-Client-Id":      vars.clientId
  }]]]></http:headers>
</http:request>

Step 7: Plan your deployment model

Where Mule applications run affects performance, cost, security posture, and operational burden. The choice of deployment model is architectural, not operational. Make it before the first application is deployed.

Deployment model comparison

Runtime Fabric deployment via Mule Maven Plugin

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>4.2.0</version>
  <extensions>true</extensions>
  <configuration>
    <runtimeFabricDeployment>
      <uri>https://anypoint.mulesoft.com</uri>
      <muleVersion>4.6.14</muleVersion>
      <applicationName>customer-system-api</applicationName>
      <target>prod-rtf-cluster</target>
      <provider>MC</provider>
      <environment>Production</environment>
      <replicas>2</replicas>
      <vCores>0.2</vCores>
      <lastMileSecurity>true</lastMileSecurity>
      <forwardSslSession>false</forwardSslSession>
      <updateStrategy>rolling</updateStrategy>
    </runtimeFabricDeployment>
  </configuration>
</plugin>

Where most teams go wrong

The architectural decisions in this guide are not especially difficult to understand. They are difficult to enforce consistently across a growing team under delivery pressure. These are the six failure patterns that appear most often in real implementations.

1. Skipping the Process layer

The most frequent anti-pattern: embedding business logic directly in Experience APIs because it feels faster with one fewer API to build. The cost becomes visible immediately. Business logic is duplicated across every consumer that needs the same capability. When a new channel is added, the logic is reimplemented a third time, diverging slightly from the first two.

The test: if two Experience APIs contain DataWeave transformations that reference the same system data in the same way, that logic belongs in a Process API.

2. Over-granular System APIs

One System API per entity produces chatty interfaces. A Process API assembling a customer order summary should not need eight System API calls for customer, address, order header, line items, pricing, inventory, shipping, and fulfilment status.

The rule: if a Process API makes more than three sequential calls to the same System API to fulfil a single business operation, the System API is under-serving its consumers. Add a composite resource.

3. Version-free design

The first breaking change becomes an impossible choice: break existing consumers or maintain a parallel implementation indefinitely. Version from day one. Add /v1/ to every base URI before publishing the first specification to Exchange. The discipline costs almost nothing at design time and pays back every time the underlying system changes or a field is renamed.

4. Treating Anypoint Exchange as a deployment registry

Teams that publish only deployed applications to Exchange miss its primary value. Exchange is a marketplace. Publish API specifications, RAML data type libraries, example requests, Postman collections, and consumer onboarding guides before and after deployment. An API that is not discoverable in Exchange is an API that will be reimplemented by the next team that needs the same capability.

5. No canonical data model

Building System APIs that expose backend-native field names and expecting each Process API to handle translation independently means the transformation tax is paid repeatedly, in different ways, by different developers. A field renamed in the source system requires finding and updating every transformation across every API that references it.

Start with a bounded context model at minimum. Publish it to Exchange as a RAML library. Even a partial EDM covering the two or three highest-traffic domains pays back within the first architecture review cycle.

6. Neglecting operational readiness

An API-led architecture that goes live without structured logging, a correlation ID strategy, alerting thresholds, and documented runbooks is one that will be blamed for every outage regardless of where the fault lies. Observability is not an operational concern separate from architecture. Wire the correlation ID propagation, the JSON logger, and the Anypoint Monitoring alerts before the first deployment, not after the first production incident.

The AI angle: what API-led architecture enables next

The three-layer model was designed for human developers consuming APIs. AI agents consume APIs too, and they do so differently: autonomously, at unpredictable call rates, across multiple systems simultaneously, and without the self-throttling behaviour a human developer applies. This changes the operational requirements of a well-governed API-led architecture without changing the architectural fundamentals.

Organisations that have built a clean API-led architecture are already positioned for the next shift. The API catalogue in Anypoint Exchange, the governance policies in API Manager, and the reusable Process API capabilities become the control plane for agentic AI workloads. An agent that discovers and calls your Customer Onboarding Process API operates within your existing governance boundary. An agent that connects directly to your CRM database does not.

Troubleshooting

Summary

API-led connectivity is an architectural commitment, not a platform feature. The discipline of designing clean layer boundaries, naming APIs after business capabilities, versioning from day one, and governing the API lifecycle is what separates an application network that compounds in value from one that becomes a new form of technical debt.

The single most important operational constraint to carry into production: every API layer must propagate a correlation ID on every request. Without it, cross-layer failure diagnosis in a three-tier architecture requires log correlation across three separate applications, three log streams, and potentially three teams. Structure your logging and your HTTP headers before the first deployment.

Key takeaways

• Build your System API surface from a complete, documented system inventory. One system of record, one System API. Shared System APIs across domains introduce coupling that is expensive to undo.
• Write the RAML or OpenAPI specification and publish it to Exchange before writing implementation code. The spec is the contract.
• Name Process APIs after business capabilities such as customer-onboarding and order-management, never after systems such as sap-connector.
• Choose your data model strategy per layer: Enterprise Data Model for enterprise-wide domains, bounded context for domain-specific APIs, mirrored model only as a pragmatic starting point with a migration plan.
• Apply OAuth 2.0 and threat protection policies at the Experience layer via API Manager. Use mTLS or JWT bearer token validation for internal layer-to-layer calls. System APIs must never be reachable from external networks.
• Set autodiscovery and api.id on every deployed API. An API without autodiscovery is invisible to API Manager. Policies, contracts, and SLA tiers do not apply until autodiscovery is active.
• Govern with Exchange from day one. Publish specifications, mark deprecated versions, and track consumer dependencies before the catalogue grows large enough that retroactive governance becomes impractical.