API Led Connectivity Architecture

API-Led Connectivity Architecture

This skill activates when an architect needs to design or evaluate an API-led connectivity architecture for Salesforce integrations using MuleSoft or equivalent middleware. It covers layer assignment, governance policy, multi-consumer strategy, and Agentforce Agent Fabric integration — distinct from the mechanics of individual callout implementation or retry backoff patterns.

Before Starting

Gather this context before designing API layer architecture:

• API-led connectivity assigns every integration to one of three layers: System (backend abstraction), Process (cross-system orchestration), Experience (consumer-tailored). The primary benefit is change isolation: a backend system change requires only a System API update; consumers are shielded.
• Governance is the architect-level concern in this domain. A technically correct three-tier design fails in production if there is no catalog, no versioning policy, and no deprecation timeline. All three are required.
• Agentforce agents consume backends via Experience APIs through MuleSoft Agent Fabric. Agents do not call System or Process APIs directly; routing through Experience APIs provides security control, rate limiting, and schema stability for agent consumers.
• The most common wrong assumption: all integrations require all three layers. Single-consumer, simple pass-through integrations justify a System API only. Adding Process and Experience layers for every integration introduces latency and maintenance overhead without benefit.
• Salesforce acts as BOTH a System-layer endpoint (when other consumers read Salesforce data via a System API) AND an Experience-layer consumer (when Salesforce calls Experience APIs to retrieve or write data to external backends).

Core Concepts

Three-Tier Layer Model

System APIs abstract a single backend system. They expose a stable contract regardless of the underlying system's protocol, schema, or version. One System API per backend system. They are generic — they do not know who is calling or why.

Process APIs orchestrate across multiple System APIs to implement a business process. A "Create Order" Process API might call an ERP System API (to create the order), a billing System API (to create an invoice), and a Salesforce System API (to update the opportunity). Process APIs know about business logic; they do not know about the shape the consumer needs.

Experience APIs adapt the output of Process or System APIs to the specific needs of one consumer type (mobile app, Salesforce UI, partner portal, Agentforce agent). Experience APIs are consumer-specific: the same underlying Process API may have multiple Experience APIs wrapping it for different consumers. This is where response shaping, field filtering, and consumer-specific rate limits live.

Governance Requirements

Every API regardless of tier requires four governance artifacts before going to production:

1. Exchange catalog entry — discoverable name, description, SLA, owner, contact
2. Versioning policy — semantic versioning (MAJOR.MINOR.PATCH); MAJOR version bumps break contract and require consumer migration
3. Deprecation timeline — minimum 90 days notice before decommissioning any version; consumers must be notified directly
4. Rate limits — designed top-down from Experience API consumer needs; Process and System API limits set to accommodate peak Experience API load plus 20% headroom

Governance without tooling is not governance: every Exchange catalog entry must be enforced at deploy time, not documented in a spreadsheet.

Agentforce Agent Fabric

Agentforce agents call external systems through MuleSoft Agent Fabric, which connects agents to Experience APIs. The architecture:

• Agent Action → Agent Fabric → Experience API → Process API → System API → Backend
• Experience APIs exposed via Agent Fabric must have explicit agent-specific rate limits (agents can fire many concurrent requests during autonomous task execution)
• Authentication uses OAuth 2.0 with dedicated client credentials per agent — shared credentials are a security anti-pattern
• Agent Fabric provides audit logging of every agent callout; this log is the primary evidence trail for agent governance

Rate Limit Design (Top-Down)

Rate limits cascade top-down. Design in this order:

1. Set Experience API consumer limit (e.g., mobile app: 1,000 req/min, Agentforce: 500 req/min)
2. Sum all Experience API limits that fan into the Process API; add 20% headroom → Process API limit
3. Sum all Process API limits that call the System API; add 20% headroom → System API limit
4. Validate System API limit is within the backend system's published capacity

Designing bottom-up (starting at the backend) results in System API limits that look correct but allow cascading exhaustion when multiple Experience APIs call the same Process API simultaneously.

Common Patterns

Pattern: Multi-Consumer with Separate Experience APIs

When to use: Multiple consumers (Salesforce UI, mobile, partner portal, Agentforce agent) need data from the same backend but with different response shapes, authentication, or rate limits.

How it works:

• One System API per backend system (e.g., system-erp-orders-api)
• One Process API per business process (e.g., process-order-fulfillment-api)
• One Experience API per consumer type:
  • experience-salesforce-orders-api — full order detail for CRM reps
  • experience-mobile-orders-api — lightweight summary for mobile app
  • experience-agent-orders-api — structured for Agentforce tool schema
• Each Experience API has its own rate limit, authentication client, and catalog entry
• Backend change (ERP schema update) requires updating only system-erp-orders-api — all consumers are shielded

Why not one API for all consumers: A single shared API requires every consumer to accept the most complex response shape; rate limits apply uniformly and cannot be tuned per consumer; one consumer's traffic pattern can starve others.

Pattern: Layer-Skip with Architecture Decision Log Entry

When to use: A single-consumer, simple read-only integration where a full three-tier stack introduces latency and maintenance cost with no benefit. Example: one Salesforce org reads a single product catalog endpoint from an internal system, with no other consumers and no anticipated consumers.

How it works:

• Build a System API only (backend abstraction layer)
• Salesforce calls the System API directly (skipping Process and Experience layers)
• Document the skip decision in the Architecture Decision Log (ADL):
  • Which layers were skipped and why
  • Consumer count (single) and anticipated growth (none)
  • Trigger for re-evaluation (if a second consumer is added, add Experience API within 30 days)

Why this is acceptable: Layer-skipping for genuinely simple, single-consumer integrations is not an anti-pattern — it is a documented, intentional tradeoff. The risk is undocumented layer-skipping that never gets revisited when a second consumer appears and the System API is directly exposed to multiple consumers without governance.

Decision Guidance

Recommended Workflow

1. Inventory integrations and consumers. List every backend system being integrated and every consumer type (Salesforce apps, mobile, agents, partners). Identify which consumers share the same backend and whether their response shape requirements differ.
2. Assign each integration to a tier. Apply the three-tier model: one System API per backend; one Process API per cross-system business process; one Experience API per distinct consumer type. For single-consumer pass-through integrations, document the layer-skip decision in the ADL.
3. Design rate limits top-down. Start from Experience API consumer limits; calculate Process and System API limits by summing consumer fanout plus 20% headroom. Validate against backend system capacity.
4. Define governance requirements for each API. For every API: create Exchange catalog entry with owner and SLA, define versioning policy (semantic versioning), document deprecation timeline (minimum 90 days), and set rate limits.
5. Design Agentforce integration points. For any Agentforce agent that calls external systems: route through Agent Fabric to an Experience API with dedicated OAuth client credentials and agent-specific rate limits; confirm audit logging is enabled.
6. Review for anti-patterns. Check: no layer-skipping without ADL entry; no shared credentials across consumers; no rate limits designed bottom-up; no Experience APIs exposing raw System API responses without shaping.
7. Document architecture decisions. Record every layer-skip decision, versioning policy exception, and rate-limit tradeoff in the ADL so future maintainers understand why the architecture looks the way it does.

Review Checklist

• Every integration assigned to correct tier (System / Process / Experience) or layer-skip documented in ADL
• One System API per backend system (not per consuming team)
• Separate Experience APIs for consumers with different response shape, rate limit, or auth requirements
• Agentforce agents routed via Agent Fabric with dedicated OAuth client per agent
• Rate limits designed top-down (Experience → Process → System)
• Exchange catalog entry exists for every API (name, owner, SLA, contact)
• Versioning policy defined (semantic versioning, MAJOR = breaking change)
• Deprecation timeline documented (minimum 90 days) for any API being decommissioned
• No undocumented layer-skipping

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. LLMs prescribe all three layers for every scenario — Applying System + Process + Experience to a single-consumer, simple pass-through integration is over-engineering that adds latency (three network hops instead of one) and three times the maintenance surface. For single-consumer integrations with no anticipated second consumer, a System API only is the correct architecture. Document it in the ADL so it is not mistaken for a governance gap later.

2. Salesforce is both a System-layer endpoint AND an Experience-layer consumer — Teams that treat Salesforce as only a consumer miss the requirement to expose Salesforce data through a System API for other systems to consume. If the ERP needs to read Salesforce opportunity data, that flow requires a Salesforce System API. Failing to design this layer forces the ERP to call Salesforce directly with its own credentials and schema assumptions — creating hidden coupling.

3. Rate limits not propagated down — cascade exhaustion — If Experience API rate limits are set without calculating the Process and System API load they generate, a peak usage event can exhaust Process or System API limits while all Experience APIs appear within limit. Top-down rate limit design prevents this. This is particularly acute when Agentforce agents fan out many concurrent Experience API calls during autonomous task execution.

Output Artifacts

Related Skills

• integration/integration-pattern-selection — upstream pattern selection before layer design
• integration/api-error-handling-design — HTTP error response contracts within API layers
• integration/error-handling-in-integrations — orchestration-layer error handling after the API layer is designed
• integration/retry-and-backoff-patterns — HTTP retry backoff for callouts within Experience or System APIs