API Architecture

The Salesforce API Landscape

Salesforce is one of the most API-rich enterprise platforms in existence — but the richness comes with complexity. There are five distinct API families, each built for a different pattern of data access, each with different performance characteristics and rate limits. Developers who use REST API for everything, or who reach for SOAP API out of habit, are making architectural decisions by default. This tutorial makes those decisions explicit.

The Five Families

REST API: JSON-over-HTTP, resource-oriented, the default choice for modern integrations. Supports CRUD on all Salesforce objects, SOQL execution, and most platform operations. Rate-limited by org-level daily API calls.

SOAP API: XML-over-HTTP, action-oriented, the legacy standard that predates REST. Same capabilities as REST API but with richer error handling via SOAP Faults and support for operations like merge() and convertLead() that REST doesn't expose directly.

Bulk API 2.0: Asynchronous, batch-oriented, designed for high-volume data operations. Processes records in batches of up to 150M per job. Does not consume daily REST/SOAP API call limits — has its own separate concurrency limits.

Streaming API (CometD): Push-based, long-polling, for real-time event consumption. Includes Platform Events channel, CDC channel, and legacy PushTopics. Not a request-response API — a subscription-based event stream.

Metadata API: For deploying and retrieving Salesforce configuration (metadata). Not for data access — for the DevOps pipeline, not the integration architecture.

REST API: The Default Choice and Its Limits

REST API is the right default for modern integrations: it's well-documented, supports JSON natively, and is the basis of most Salesforce SDKs and client libraries. For integrations that do real-time record retrieval, create/update operations on individual records, and SOQL execution, REST API is usually the correct choice.

REST API Capabilities

Key REST API capabilities: CRUD on any Salesforce object (/sobjects/{ObjectType}/{Id}), SOQL execution (/query?q=SELECT...), composite operations (up to 25 subrequests in a single HTTP call), upsert by external ID, and Apex REST if you need custom endpoint logic. The composite API is particularly valuable for reducing call volume — batch multiple related operations into a single API round-trip.

// REST API: Composite request — create Account and related Contact in one call
// POST /services/data/v59.0/composite

{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/v59.0/sobjects/Account",
      "referenceId": "newAccount",
      "body": {
        "Name": "Acme Corp",
        "Industry": "Technology"
      }
    },
    {
      "method": "POST",
      "url": "/services/data/v59.0/sobjects/Contact",
      "referenceId": "newContact",
      "body": {
        "FirstName": "Jane",
        "LastName": "Smith",
        "AccountId": "@{newAccount.id}"
      }
    }
  ]
}

Where REST API Hits Its Limits

REST API is not appropriate for: high-volume batch processing (use Bulk API 2.0), real-time event streaming (use Streaming API / CDC), or operations that require richer SOAP semantics like merge() or convertLead(). It's also not appropriate when your integration pattern will consume more than 20% of the org's daily API limit — any integration consuming that much volume should use Bulk API or an event-based pattern to reduce call frequency.

SOAP API: Still Relevant, Here's Why

SOAP API is frequently dismissed as legacy. That dismissal ignores several genuine reasons it remains in use in enterprise contexts. First, SOAP API supports operations that REST API doesn't expose: merge() (merge duplicate records), convertLead() (convert Lead to Account/Contact/Opportunity as a single transaction), process() (submit records to approval processes). If your integration needs these operations, SOAP API is not optional.

Second, SOAP's typed XML with WSDL-based schemas has advantages for certain enterprise integration platforms (MuleSoft, IBM App Connect, older BizTalk integrations) that generate typed clients from WSDLs. The tooling in those platforms often makes SOAP integrations easier to maintain than equivalent REST integrations.

Third, SOAP's fault handling is richer than REST's HTTP status codes for certain error conditions — particularly partial success scenarios in batch operations, where SOAP's compound response model is more expressive than REST's error body conventions.

Bulk API 2.0: The Right Tool for High-Volume Operations

Bulk API 2.0 is architecturally different from REST and SOAP APIs. It's asynchronous: you create a job, upload a CSV, wait for processing, and retrieve results. It processes records in parallel batches of 10,000. It does not count against your daily REST/SOAP API call limit. For any operation involving more than a few thousand records, Bulk API 2.0 should be the default choice.

Key characteristics: supports Insert, Update, Delete, Upsert, and Query operations. Query via Bulk API returns up to 150M records without timeouts (unlike SOQL which times out on non-selective queries at large volumes). Uses CSV format, not JSON. Jobs are asynchronous — poll for status or use event notification when complete.

The architectural implication: if your nightly data sync from an external system updates 50,000 Account records, doing this via 50,000 REST API calls will consume a significant portion of your daily API budget and fail on rate limits. Doing this via a single Bulk API 2.0 job uses no daily API calls and processes in minutes.

Streaming API: Event-Driven Real-Time Integration

The Streaming API (based on the CometD protocol with Bayeux long-polling) is Salesforce's push-based mechanism for subscribing to real-time events. Three main subscription channels: Platform Events (/event/{PlatformEventName__e}) for custom application events, Change Data Capture (/data/{ObjectName}ChangeEvent) for automatic CRM record change events, and PushTopics (legacy, being replaced by CDC) for SOQL-based polling subscriptions.

Streaming API is not a polling API — it's a subscribe-and-receive model. External systems maintain a persistent connection and receive events as they occur. This is architecturally superior to polling for use cases where you need near-real-time notification of Salesforce record changes without consuming REST API call quotas on each poll cycle.

GraphQL API: The New Option Worth Understanding

Salesforce introduced a native GraphQL API in 2023 (GA in Winter '24). GraphQL allows clients to specify exactly which fields they need in a single query, reducing over-fetching (a common problem with REST API where all fields are returned) and enabling efficient retrieval of related object graphs in a single request.

GraphQL is valuable for: frontend applications that need precise field selection for performance, complex relationship traversals that would require multiple REST API calls, and use cases where network bandwidth is constrained (mobile, IoT). It uses the same authentication and rate limits as REST API. For backend integrations where field selection is predictable, REST remains simpler. For flexible frontend-driven data access, GraphQL's query flexibility is genuine value.

API Governance: Rate Limits, Monitoring, and Budget Architecture

API governance is treating your org's API call budget as a shared resource that requires active management, not passive monitoring after breaches. The elements of API governance:

Inventory: Document every integration that calls the Salesforce API, its approximate call volume per day, and its peak call rate. This inventory rarely exists in mature orgs and is the first step in understanding your actual API consumption.

Monitoring: Salesforce provides API usage data via the ApiEvent EventLog file (Shield required for detailed logs) and aggregate usage via Setup → Company Information. Set up alerts when daily consumption exceeds 70% of limit — not 100%, because 70% leaves headroom for unexpected spikes.

Optimisation: Any integration making more than 1,000 calls/day should be reviewed for Bulk API or CDC alternatives. Composite API should be used wherever multiple related operations are called sequentially. Caching frequently-read reference data (metadata, lookup values) eliminates unnecessary calls entirely.