API-led connectivity applied to a Salesforce estate

Draw the three layers, label the boxes System, Process and Experience, and the room nods along. Then somebody asks which box the Account object goes in, and the nodding stops.

API-led connectivity is a sound organising idea and the diagram is a fair summary of it. What it does not carry is any of the decisions that decide whether the layering repays the effort: what one System API covers, how coarse it should be, where logic specific to your org may sit, and whether the top layer is needed at all. Those get settled in the first fortnight by whoever writes the first interface, and they are expensive to revisit once four consumers depend on the shape.

This piece puts a Salesforce estate underneath the boxes.

#What a System API covers when the system is Salesforce

A System API exposes an underlying system in that system own terms, with no knowledge of who is calling or why. For a database that is straightforward. For Salesforce it is less obvious, because Salesforce is not one system. It is a platform hosting several, and the objects belonging to sales, service, field operations and billing sit in the same org behind the same API.

So the first question is not how to wrap Salesforce. It is which part of Salesforce a given System API speaks for.

Scope each one to a bounded capability inside the org rather than to the org itself. A customer System API covers Account, Contact and the relationship between them. An opportunity System API covers Opportunity, its line items, and the price book reads that make a line item meaningful. A case System API covers Case, its comments and its attachments. Each is coherent, and each can change on its own release cycle.

Inside, it is Salesforce vocabulary cleaned up. Field names normalised into something a developer can read without the org open in another tab. Record type resolved rather than exposed as an eighteen-character identifier. Picklists passed as API names rather than labels, because labels get translated and reordered by people not thinking about your integration. Pagination, error mapping and retry handled once.

#One System API per object is the most common way to get this wrong

The instinct, when a team is asked to build System APIs over Salesforce, is to enumerate the objects and build one each. Account API, Contact API, Opportunity API, Case API. Tidy on a wiki page, and an estate nobody can use without stitching.

The problem appears with the first real consumer. Creating a customer in Salesforce is not one object. It is an account, at least one contact, a relationship between them, and often an address and defaults that depend on the account type. With one API per object, that consumer makes four calls in an order it has to know, holds partial state between them, and decides for itself what happens when the third fails after the first two succeeded. The distributed transaction problem has been pushed out of the integration layer and into every application touching it, and each solves it differently.

Scope by bounded capability instead: what a consumer needs to accomplish in the source system, in the source system terms. Maintain a customer. Update an opportunity with its lines. Progress a case. Inside that boundary the System API owns the ordering and the compensation, and outside it consumers see one call. The test: if a consumer must make three calls in sequence and unwind them itself when the second fails, the boundary is in the wrong place.

The symmetric error is rarer and worse. One System API for the whole org, sixty operations versioned as one thing, so a change for the service team drags the sales team into regression testing. The right boundaries usually sit where the org is already administered separately.

#Salesforce-specific logic in a System API destroys the thing you built it for

This is the failure that costs the most and surfaces the latest.

A System API is meant to be the one place that knows how to talk to Salesforce, and nothing more. The moment it also knows that opportunities above a certain value need a second approver, or that a case from the partner portal skips first-line triage, it is not a System API. It is a business process with a connector attached.

The objection is not purism. Three consequences follow.

The API can no longer be reused. The next consumer wants the same customer data without your approval rule. It cannot have it, so it either builds a second API over the same objects or asks for a flag. Flags accumulate, and within a year the parameter set encodes the differences between four consumers. Reuse has become branching.

Cheap changes become expensive. An approval threshold moves, a five-minute decision in the business, and it now requires a change to a shared component four consumers depend on, with all their regression testing attached.

Nobody can find the rule. Somebody looking for where the threshold lives will look in Salesforce, then in the orchestration, and will not think to look inside the connectivity layer. Logic hidden a layer below where anyone expects it gets duplicated rather than found.

The line to hold is short. A System API may know how Salesforce works. It may not know how your business works. Field mapping, record type resolution, defaults required for the object to save at all, error translation and idempotent upsert on an external identifier are fair. Conditional behaviour that would change if the business changed its mind is not.

#The Process layer, and the discipline that keeps it thin

Process APIs are where the logic just evicted from the System layer lives, and this is the layer most estates leave thinnest.

A Process API composes calls across System APIs to do something the business recognises. Onboard a customer: create the customer through the customer System API, the billing account through the finance System API, the entitlement through the contracts System API, return one result. None of that sequence belongs to a single source system, which is why it needs its own home.

Three things belong here and nowhere else. Orchestration, the order of calls and the dependencies between them. Compensation, what gets undone when step three fails after steps one and two committed, which is a business decision rather than a technical one. Cross-system mapping, between the finance system idea of a customer and the Salesforce idea of an account.

The discipline problem is that a Process API is a comfortable place to put anything at all. It is code, it deploys, it needs no Salesforce admin, and it escapes the reuse conversation. Left alone it becomes a second home for business logic, holding rules that quietly contradict what is already configured in the org, discoverable only by reading it.

Two rules keep it honest.

A Process API calls at least two System APIs, or it is not orchestrating anything. A process layer fronting a single system is a pass-through with a deployment pipeline, and it should be deleted rather than documented.

Logic the platform already enforces is not re-implemented here. Where validation rules, approvals or Flow already encode a rule, the Process API calls Salesforce and lets Salesforce enforce it. Duplicating it produces two versions that agree until somebody changes one.

#Experience APIs, and whether you need them at all

Experience APIs shape a response for one specific consumer: a mobile app needing a flattened payload over a poor connection, a partner portal that must see a deliberately reduced view, a public web form.

They are real, and most Salesforce estates do not need them.

The dominant consumers of a Salesforce integration layer are systems, not interfaces. An ERP consuming customer changes wants a stable contract that does not move, not a bespoke shape. An Experience API in front of a Process API for one system consumer buys another component to version, deploy and monitor, in exchange for a payload the consumer could have accepted as it was.

Build one when all three answers are yes. The consumer needs a genuinely different shape rather than a subset. That shape will move on the consumer release schedule rather than yours. Shielding the layers beneath from that churn has value. A mobile app under active development qualifies; a nightly finance extract does not.

Skipping the layer is not a compromise. Where every consumer is a back-office system, two layers is the right architecture, and the third box gets drawn only because the diagram has three boxes in it.

#The layers against a real estate

Fill the table in for your own estate before the first build. The third column settles arguments, the fourth prevents them.

#When MuleSoft is not the answer

The platform earns its place where there are several systems, several consumers, and interfaces that will outlive the projects building them. It does not earn its place on enthusiasm.

A single point-to-point interface does not justify a platform. One nightly extract from one system into Salesforce, with no second consumer in prospect, is a nightly extract. Layering it adds a runtime, a pipeline, a monitoring surface and a skill set somebody has to keep current, in exchange for reuse that will never be claimed. An honest account of API-led connectivity includes the case where the answer is a scheduled job and a well-scoped integration user.

Signals it is not yet warranted: one or two interfaces, all between the same pair of systems; no identified second consumer; a team with no capacity to operate another runtime, the constraint most often left unstated.

Signals it is: a rising count of direct connections where a change at one endpoint requires a survey of the others; the same data pulled from the same source by three teams who each wrote their own version; and a real need for the operational surface of full lifecycle API management, meaning policy, throttling, access control and consumption visibility as products rather than as things each integration writes again.

Whether to run a platform at all is a different question from how any single interface should behave, which we cover in pick the integration pattern before you pick the middleware.

#Reuse is the entire economic case, and it usually fails

Layering costs more than not layering: three components instead of one, three deployments, three sets of tests. That cost is repaid only when the second and third consumers use what the first one built, and across a lot of estates the repayment never arrives.

It fails for reasons that are predictable and mostly not technical.

The first consumer shaped the contract around itself. Built to a deadline for one project, the API carries that project assumptions in its field set and its granularity. The second consumer finds it nearly right, and nearly right is often more expensive than starting again.

Nobody knows it exists. An API that is not catalogued, not documented with an example a developer can run, and not findable outside the original project gets rebuilt by the next team, who will be genuinely unaware.

The second consumer cannot get a change made. They need one extra field. The owning team has its own backlog and release train. Six weeks of waiting against two days of forking is not a close decision under delivery pressure, and the fork is where the estate fragments.

Versioning was never designed. Without a policy agreed before the first release, every change is potentially breaking, consumers freeze on the version they integrated against, and the API ossifies into as many variants as it has callers.

What makes reuse happen is unglamorous. Sketch the second and third use case while designing the first, because half a day changes the granularity. Publish a catalogue somebody outside the integration team can browse. Agree the versioning policy before the first release rather than at the first breaking change.

None of that is platform configuration. It is the part of an iPaaS programme the tooling cannot do for you, and it decides whether the layering was worth building.

#What to settle before the first API

Draw the bounded capabilities in your org, usually three to six, usually already visible in how it is administered. Fix the granularity test so the first developer is not inventing one. Put the single line about Salesforce-specific logic in the review checklist, because it is the rule most often broken by people who agreed with it. And decide explicitly whether you are building two layers or three.

Two adjacent decisions belong alongside these. Who holds an interface once the project that built it has closed is a programme-level question, set out in integration at programme level. And where a programme is unifying customer data rather than moving it, the decisions taken before ingestion are covered in getting Data 360 right the first time.

The layers are worth drawing. They are worth building when the boundaries follow real capabilities in your org, the logic sits where the next person will look for it, and somebody can find the API without knowing who wrote it.