API-First vs Integration-First Architecture: The Strategic Choice

Two Strategies That Are Often Confused

API-first is a design methodology: you design the API contract — its endpoints, request/response schemas, authentication model, and versioning strategy — before writing a single line of implementation code. The API is the first citizen; the implementation is secondary. This approach prioritises consumer experience (the developers or systems consuming the API) and forces explicit thinking about contracts, backward compatibility, and discoverability. It became mainstream alongside RESTful APIs and the proliferation of mobile applications that needed stable, versioned interfaces to back-end services.

Integration-first is an architectural strategy: you treat the movement of data and process between systems as a first-class architectural concern, not an afterthought solved by whoever owns each system. Integration-first organisations build integration capabilities (a platform, a pattern library, an operations model) before they need them, rather than building point-to-point connections ad hoc and regretting it three years later when they have 400 integrations with no central visibility.

In the Salesforce context, this distinction manifests concretely. An organisation doing a Salesforce implementation decides to use Connected Apps and Named Credentials to secure all Salesforce API access (good API hygiene, but not API-first design). Separately, it decides that all integrations with Salesforce must flow through a MuleSoft runtime layer with centralised monitoring (integration-first thinking). These decisions are complementary but they are made in different contexts, by different stakeholders, and with different evaluation criteria.

What API-First Requires in Practice

API-first is not simply "design before build." It requires a specific organisational capability: the ability to publish an API specification, get feedback from consumers before implementation, and treat the specification as a contractual artefact that outlasts any given implementation. In MuleSoft's ecosystem this is delivered through Anypoint Exchange, where API specifications (typically written in RAML or OAS 3.0) are published and discoverable before a single runtime is deployed. In the Salesforce ecosystem, it maps to defining a Connected App's permission scopes and API contract before the Apex REST service is written.

The practical requirements of API-first include a specification language and tooling (RAML, OAS 3.0, AsyncAPI for event-driven APIs), a design review process that involves potential consumers, a versioning strategy (URI versioning, header versioning, or content negotiation), and a deprecation policy. Without these, "API-first" becomes "we write the Swagger docs after the implementation" — which is documentation-first, not API-first, and delivers substantially less value.

# OAS 3.0 snippet: Salesforce Account API contract defined before implementation
openapi: 3.0.3
info:
  title: Customer Account API
  version: "2.1"
  description: Canonical API for Customer Account operations
paths:
  /accounts/{accountId}:
    get:
      summary: Retrieve a single Account by Salesforce ID
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9A-Za-z]{15,18}$'
      responses:
        "200":
          description: Account found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        "404":
          description: Account not found
components:
  schemas:
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        billingCity:
          type: string
        annualRevenue:
          type: number
          format: double
      required: [id, name]
# This contract is published to MuleSoft Anypoint Exchange BEFORE
# the Apex REST resource or MuleSoft flow is implemented.
# Consumer teams mock against it immediately.

The benefit of publishing a mock before implementation is that consumer teams can begin building against it immediately. If the consumer team discovers that the API design is wrong — the schema is missing a field, the endpoint structure doesn't match how they need to query — the change is cheap because nothing has been built yet. This is the core value proposition. An API discovered to be wrong after six consuming integrations are live costs orders of magnitude more to fix.

MuleSoft API-Led Connectivity: The Three-Layer Model

MuleSoft's API-led connectivity framework is the most influential architectural pattern for organisations combining API-first design with integration-first thinking. It divides the integration landscape into three horizontal layers, each with a distinct purpose and consumer audience.

The System Layer contains APIs that wrap individual backend systems — one System API per core system. A Salesforce System API exposes raw Salesforce operations (create Account, query Opportunity, publish Platform Event) without business logic. An SAP System API exposes SAP BAPI calls without any knowledge of how Salesforce uses them. System APIs are owned by the teams that own the respective systems, versioned conservatively, and expected to have high availability because many Process APIs depend on them.

The Process Layer contains APIs that orchestrate calls across multiple System APIs to implement a business process. An "Order Fulfilment" Process API might call the SAP System API to create a delivery, the Salesforce System API to update the Order status, and the ERP System API to post a financial document — in sequence, with error handling and compensation logic. Process APIs encode business rules and are owned by the business process owners, not the IT system teams.

The Experience Layer contains APIs tailored to specific consumer channels: a mobile app, a partner portal, a customer self-service community. Experience APIs can aggregate data from multiple Process APIs, apply channel-specific transformation (e.g., returning a lightweight summary for mobile vs a detailed record for desktop), and handle channel-specific authentication. Salesforce Experience Cloud APIs, Community REST APIs, and the Salesforce Mobile SDK all represent Experience Layer consumption patterns in the Salesforce context.

Integration-First Thinking: What It Changes

An integration-first organisation treats integration as a platform, not a project. When a new system is being evaluated for procurement, the integration team is involved in the evaluation — not as an afterthought after the contract is signed, but as a key evaluator asking whether the system's integration capabilities (available APIs, event model, bulk data access) meet the organisation's integration standards. Systems that don't support the organisation's integration platform (or require bespoke adapters that only that vendor can build) carry a higher TCO that must be factored into the procurement decision.

Integration-first changes the project governance model. Every project that connects two or more systems produces integration assets — API specifications, MuleSoft flows, Informatica mappings — that must be registered in the central integration catalogue. These assets are not owned by the project that created them; they are owned by the integration platform team and are available for reuse. This prevents the duplication of integration logic that is endemic in organisations where every project builds its own connections.

Integration-first also changes the incident response model. When an integration fails in a point-to-point world, two system teams argue about whose system caused the failure. When integration runs through a central platform, the integration team owns the monitoring, the alerting, and the initial triage. The integration team knows which downstream systems are affected by a given failure and can communicate impact proactively rather than reactively.

The Salesforce-Specific Tension

Salesforce creates a specific tension for API-first and integration-first strategies. Salesforce is simultaneously an integration consumer (it needs data from ERP, HRIS, and legacy systems), an integration producer (it exposes rich APIs that consuming systems call), and increasingly an integration platform itself (Platform Events, Change Data Capture, Data Cloud, MuleSoft). Deciding how much integration logic to put inside Salesforce vs. outside Salesforce on a dedicated integration platform is one of the most consequential architectural decisions an organisation makes.

Putting integration logic inside Salesforce (Apex callouts, Process Builder flows that call external actions, Platform Events consumed by external systems) has the advantage of simplicity for small-scale requirements and no additional licensing cost. It has the disadvantage of coupling the integration logic to Salesforce's governor limits, deployment model, and testing framework. When an Apex callout fails, debugging it requires access to Salesforce debug logs — not the integration platform's centralised logging.

The practical guidance: any integration that requires more than two external system calls, has complex error handling and compensation logic, involves batch or bulk processing, or needs centralised monitoring and SLA management should live on the integration platform, not inside Salesforce. The Salesforce side of that integration should be limited to publishing events, receiving webhooks, and exposing clean, versioned APIs.

Making the Strategic Choice

When an organisation needs to choose between prioritising API-first and integration-first investment — and most organisations do need to choose because they can't fully invest in both simultaneously — the decision factors are the organisation's current integration pain and its primary integration drivers.

Organisations whose primary pain is that systems are directly connected to each other without any central visibility, monitoring, or reuse should invest in integration-first capabilities first. Build the integration platform, establish the integration patterns, onboard the highest-traffic integrations to the platform before investing heavily in API contract design methodology. A beautifully designed API specification published in Anypoint Exchange does not help if the runtime underneath it is a tangle of undocumented point-to-point connections.

Organisations whose primary pain is that internal teams are building redundant integrations because they can't discover what already exists, or that partner and customer developers are unable to consume Salesforce capabilities because the APIs are inconsistent and undocumented, should prioritise API-first investment. Design and publish API contracts, build an API portal, establish versioning standards, and make existing APIs discoverable before building net-new integration infrastructure.

Mature organisations — those with both a functioning integration platform and a published API catalogue — can pursue both strategies simultaneously, with API-first governing how capabilities are exposed and integration-first governing how data and process flow between systems. This is the target state, but it takes years to reach and requires sustained executive sponsorship because neither strategy delivers short-term cost reduction on its own.