API-Led Connectivity

API-led connectivity splits integration APIs into three layers — system, process, and experience — so each layer has one clear job and one clear owner.

At a glance

• What it is: A layering discipline for APIs: system APIs wrap a single backend system (hiding its quirks), process APIs combine multiple system APIs into a business process, and experience APIs shape data for a specific consumer (a mobile app, a partner, a web frontend).
• Why it matters: Without layering, one API ends up doing backend access, business logic, and consumer-specific formatting at once — so every new consumer or backend change forces a change to the same overloaded endpoint.
• For developers: if you’re about to add a “just this one extra field for the mobile team” parameter to a backend-facing API, that’s usually a sign you need an experience API layer instead of bending the system API.
• When to use it: When more than one consumer needs the same underlying system data, or when a business process spans more than one backend system.
• When not to use it: For a single internal service with one consumer — three layers of API for one caller is unnecessary ceremony.
• Prerequisites: Integration Patterns & Styles.

Mental model

graph LR
    M[Mobile App] --> EXP1[Experience API: Mobile]
    W[Partner Web] --> EXP2[Experience API: Partner]
    EXP1 --> PROC[Process API: Place Order]
    EXP2 --> PROC
    PROC --> SYS1[System API: Orders]
    PROC --> SYS2[System API: Tax]
    PROC --> SYS3[System API: Fraud Check]
    SYS1 --> DB1[(Orders DB)]
    SYS2 --> EXT1[Tax Partner]
    SYS3 --> EXT2[Fraud Partner]

Requests flow top-down through the layers and responses flow back up — each layer only knows about the layer directly below it, not what’s underneath that.

Step-by-step walkthrough

1. Identify the backend system(s) involved and create (or reuse) one system API per backend, hiding that system’s protocol/format quirks.
2. Identify the business process that spans those systems and create one process API that orchestrates calls to the relevant system APIs.
3. Identify each distinct consumer (mobile app, partner, web app) and create an experience API per consumer, shaped to exactly what that consumer needs.
4. Put an API gateway in front of the experience APIs for auth, rate limiting, and monitoring (see Integration Security & Governance).
5. Version each layer independently — a system API change shouldn’t force every experience API to redeploy.

Worked example

Continuing from Integration Patterns & Styles: the checkout system’s Cart, Pricing, and Payment modules call the tax, fraud-check, and loyalty-points partners directly from nine different places.

• Input: nine direct point-to-point partner calls with no shared structure.
• Process: create three system APIs (one per partner, hiding each partner’s own quirky format), one process API “Price and Validate Order” that calls all three system APIs, and one experience API for the checkout frontend.
• Output: the checkout frontend now calls a single experience API; adding a new consumer (e.g. a partner storefront) later only needs a new experience API, not new direct partner integrations.

// Process API: orchestrates the three system APIs behind one call
public async Task<OrderPricingResult> PriceAndValidateOrderAsync(OrderRequest request)
{
    var tax = await _taxSystemApi.CalculateAsync(request);
    var fraud = await _fraudSystemApi.CheckAsync(request);
    var loyalty = await _loyaltySystemApi.ApplyPointsAsync(request);
    return new OrderPricingResult(tax, fraud, loyalty);
}

On Azure, each layer is published as a separate product in Azure API Management — the experience API is the only one exposed externally, with the process and system APIs kept internal-only behind the gateway.

resource apim 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: 'checkout-apim'
  location: location
  sku: { name: 'Developer', capacity: 1 }
  properties: {
    publisherEmail: 'platform-team@contoso.com'
    publisherName: 'Contoso Platform Team'
  }
}

resource experienceProduct 'Microsoft.ApiManagement/service/products@2023-05-01-preview' = {
  parent: apim
  name: 'checkout-experience-api'
  properties: { displayName: 'Checkout Experience API', subscriptionRequired: true, state: 'published' }
}

resource ordersSystemApiEndpoint 'Microsoft.Network/privateEndpoints@2023-09-01' = {
  name: 'pe-orders-system-api'
  location: location
  properties: {
    subnet: { id: subnetId }
    privateLinkServiceConnections: [
      { name: 'orders-system-api-connection', properties: { privateLinkServiceId: ordersAppServiceId, groupIds: ['sites'] } }
    ]
  }
}

Only the checkout-experience-api product is published; the Orders system API’s backend has no public IP at all — it’s reachable only over this private endpoint from inside the VNet, never from the open internet.

Common use cases

Use case	Layer to add or change	Notes
New mobile app needs a trimmed-down response	Experience API	Don’t touch the process or system APIs
Business process now needs an extra backend system	Process API	Add a call to a new (or existing) system API
Backend system replaced or upgraded	System API	Only the system API implementation changes; process/experience APIs are unaffected if the contract stays stable

Advanced details

• Contract-first: design each layer’s API contract before implementation, so consumers of a layer can build against it in parallel with the backend work.
• Reuse over duplication: a system API should be reused by every process API that needs that backend, not re-wrapped per process.
• Gateway placement: the API gateway typically sits in front of experience APIs only — process and system APIs are usually internal-only, reducing what’s exposed to the outside world.

Quick reference

Term	Meaning
System API	Wraps one backend system, hides its protocol/format quirks
Process API	Orchestrates one or more system APIs into a business process
Experience API	Shapes data for one specific consumer
API gateway	Entry point handling auth, rate limiting, and monitoring for exposed APIs

Troubleshooting

Symptom	Likely cause	Fix
One API has both backend logic and consumer-specific fields	Missing layering — a system API doing an experience API’s job	Split into system + experience layers
Every new consumer requires a backend team code change	No experience API layer	Introduce an experience API per consumer, shaped independently of the backend
A business process change requires touching every backend system’s client code directly	No process API layer	Introduce a process API to hold the orchestration logic

Check your understanding

• Which layer would you add if a new partner storefront needs a cut-down version of the existing checkout experience API’s response?
• Why should a system API change ideally not require redeploying every experience API built on top of it?

Related pages

Part of Introduction to Integration Architecture. Builds on Integration Patterns & Styles; see also Integration Security & Governance for gateway-level controls, and the Glossary for term definitions.