SfSkills Domains Docs GitHub

Home / architect / api-led-connectivity-architecture

api-led-connectivity-architecture

Use this skill when designing API-led connectivity architecture for Salesforce integrations — covering System/Process/Experience layer separation, governance policy (catalog, versioning, deprecation, rate limits), multi-consumer strategy, and Agentforce Agent Fabric integration.

Open the skill folder on GitHub

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:

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:

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:

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:

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

SituationRecommended ApproachReason
Single consumer, simple pass-throughSystem API only; document layer-skip in ADLAll three layers add maintenance cost with no isolation benefit for one consumer
Multiple consumers needing same data in different shapesOne Process API + one Experience API per consumer typeExperience APIs isolate consumer-specific shaping and rate limits
Agentforce agent calling external backendExperience API via Agent Fabric; dedicated OAuth client per agentAgent Fabric provides audit, rate limiting, and security isolation required for autonomous agents
Backend system migration (ERP v1 → v2)Update System API only; no consumer changes requiredThis is the primary value of System layer — consumers are shielded from backend change
Breaking API contract change requiredMAJOR version bump; maintain old version for 90-day deprecation windowSemantic versioning + deprecation timeline prevents breaking consumers on surprise
Teams asking "do we need all three layers"Evaluate consumer count and anticipated growth; document decisionPrescribing all three layers always is an LLM anti-pattern — use ADL to make the tradeoff explicit
  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

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

ArtifactDescription
API layer assignment matrixTable mapping each integration to System / Process / Experience tier with rationale
Governance policy documentExchange catalog requirements, versioning policy, deprecation timeline per API
Rate limit designTop-down calculation from consumer limits to System API limits
Architecture Decision Log entriesADL entries for every layer-skip decision and policy exception
Agentforce integration designAgent Fabric route, OAuth client assignments, rate limits for agent consumers

Package files