Salesforce API Landscape

Salesforce exposes a wide range of APIs, each designed for specific use cases. Choosing the wrong API is a common CTA pitfall — this page covers every API you need to know, with decision criteria, volume thresholds, and rate limits.

---

API Decision Matrix

API	Protocol	Format	Best For	Volume	Direction
REST API	REST	JSON/XML	CRUD operations, modern integrations	Low-medium	Bidirectional
SOAP API	SOAP	XML	Legacy systems, full metadata access	Low-medium	Bidirectional
Bulk API 2.0	REST	CSV/JSON	Large data loads (thousands+)	High	Bidirectional
Composite API	REST	JSON	Multi-step operations, reducing roundtrips	Low-medium	Inbound
Streaming API	Bayeux/CometD	JSON	Real-time notifications (legacy)	Event-based	Outbound
Pub/Sub API	gRPC	Avro/Binary	High-throughput event streaming	Event-based	Bidirectional
Platform Events API	REST	JSON	Custom business events	Event-based	Bidirectional
Change Data Capture	Pub/Sub	Avro	Data change notifications	Event-based	Outbound
GraphQL API	GraphQL	JSON	Flexible queries, mobile optimization	Low-medium	Bidirectional
Metadata API	SOAP/REST	XML/JSON	Deployment, org configuration	N/A	Bidirectional
Tooling API	REST/SOAP	JSON/XML	Developer tools, IDE integration	N/A	Bidirectional
Analytics API	REST	JSON	CRM Analytics (Tableau CRM) data	Reports/dashboards	Bidirectional
Connect API (Chatter)	REST	JSON	Social features, feeds, communities	Low	Bidirectional
Apex REST/SOAP	REST/SOAP	JSON/XML	Custom business logic endpoints	Low-medium	Inbound

---

REST API

The most commonly used Salesforce API. JSON-based, lightweight, and suitable for most CRUD operations.

Key Characteristics

• Standard HTTP methods (GET, POST, PATCH, DELETE)
• JSON or XML payloads
• Versioned endpoints (e.g., /services/data/v60.0/sobjects/Account/)
• Supports SOQL and SOSL queries
• Named Credentials for authentication

When to Use

• Modern integrations with JSON-capable systems
• Single-record or small-batch CRUD operations
• Mobile and web application backends
• Any integration where simplicity is valued

Rate Limits

Edition	API Requests per 24 Hours
Enterprise	100,000 (base) + per-user allocation
Unlimited	500,000 (base) + per-user allocation
Per user addition	1,000 per Salesforce license, 200 per other licenses

Concurrent call limit

All API types share a concurrent long-running call limit of 25 (for total org, not per user). Calls running longer than 20 seconds count against this limit. This is one of the most commonly overlooked limits in CTA scenarios.

When NOT to Use

• Volumes exceeding a few thousand records per transaction (use Bulk API)
• When you need to subscribe to data changes (use Streaming/Pub/Sub)
• When the consumer is a legacy SOAP-only system (use SOAP API)

---

SOAP API

XML-based API using WSDL contracts. Provides the same data access as REST but with stronger typing and full metadata access.

Key Characteristics

• WSDL-based service definitions
• Enterprise WSDL (strongly typed, org-specific) and Partner WSDL (loosely typed, generic)
• Full metadata access capabilities
• Session-based authentication

When to Use

• Legacy systems that require WSDL contracts
• When you need the Partner WSDL for ISV/multi-org tools
• Metadata operations (though Metadata API is more focused)
• When strong typing and contract-first design are required

When NOT to Use

• Modern integrations (REST is simpler and lighter)
• High-volume operations (use Bulk API)
• Mobile applications (XML payload overhead)

---

Bulk API 2.0

Purpose-built for loading, querying, and deleting large datasets. Uses a job-based asynchronous pattern.

Key Characteristics

• Asynchronous, job-based processing
• CSV or JSON input/output
• Supports insert, update, upsert, delete, and hard delete
• Automatic batching by the platform
• Query all records with SOQL (Bulk Query)

How It Works

sequenceDiagram
    participant Client
    participant Salesforce

    Client->>Salesforce: Create ingest job (POST /jobs/ingest)
    Salesforce-->>Client: Job ID
    Client->>Salesforce: Upload CSV data (PUT /jobs/ingest/{id}/batches)
    Client->>Salesforce: Close job (PATCH - state: UploadComplete)
    Salesforce->>Salesforce: Process records asynchronously
    Client->>Salesforce: Poll job status (GET /jobs/ingest/{id})
    Salesforce-->>Client: Job status (InProgress/Complete/Failed)
    Client->>Salesforce: Get results (GET /jobs/ingest/{id}/successfulResults)
    Salesforce-->>Client: Success/failure details per record

Volume Guidance

Scenario	Recommendation
< 200 records	REST API (single or Composite)
200 - 2,000 records	REST API Composite or Bulk API
2,000 - 100,000 records	Bulk API 2.0 (serial mode)
100,000 - 10M records	Bulk API 2.0 (parallel mode)
10M+ records	Bulk API 2.0 + partitioned jobs + off-peak
Query large datasets	Bulk Query (Bulk API 2.0 query operation)

Serial vs Parallel Processing

Mode	Behavior	When to Use
Serial	Records processed in order, one batch at a time	Lock contention risk, parent-child relationships
Parallel	Multiple batches processed concurrently	Independent records, maximum throughput

Limits

Limit	Value
Daily Bulk API batches	15,000 per 24 hours
Max record size	10 MB per record
Max file size per upload	150 MB
Max records per 24-hour period	100 million
Query result size	1 GB per query

Serial mode for parent-child

When loading data with parent-child relationships (e.g., Accounts then Contacts), use serial mode or separate jobs with ordering. Parallel mode can cause lock contention and “UNABLE_TO_LOCK_ROW” errors. This is a frequent CTA scenario trap.

---

Composite API

Combines multiple API operations into a single HTTP request, reducing round trips. Three variants serve different needs.

Variants

Variant	Max Subrequests	Dependencies	Use Case
Composite	25	Yes (reference previous results)	Multi-step operations with dependencies
Composite Batch	25	No (all independent)	Multiple independent operations
sObject Tree	200 records	Parent-child	Creating record trees (Account + Contacts)
sObject Collections	200 records	No	Bulk CRUD on same object type

Composite Request Flow

sequenceDiagram
    participant Client
    participant Salesforce

    Client->>Salesforce: Single HTTP POST with 5 subrequests
    Note over Salesforce: Subrequest 1: Create Account
    Note over Salesforce: Subrequest 2: Create Contact (refs Account ID)
    Note over Salesforce: Subrequest 3: Create Opportunity (refs Account ID)
    Note over Salesforce: Subrequest 4: Create Task (refs Contact ID)
    Note over Salesforce: Subrequest 5: Query related records
    Salesforce-->>Client: Single response with all 5 results

Composite Subrequest Processing (Internal Flow)

Understanding how Salesforce processes subrequests internally helps explain allOrNone behavior and reference ID resolution — both commonly tested at the CTA board.

flowchart TD
    A["Client sends Composite request<br/>(up to 25 subrequests)"] --> B["Salesforce receives single HTTP POST"]
    B --> C{allOrNone = true?}

    C -->|Yes| D["Begin single transaction<br/>(all subrequests share one transaction)"]
    C -->|No| E["Partial success allowed<br/>(failures don't roll back prior successes)"]

    D --> F["Execute subrequest 1<br/>e.g., Create Account"]
    E --> F

    F --> G["Store result + reference ID<br/>@{NewAccount.id} = 001xxx"]
    G --> H["Execute subrequest 2<br/>Resolve @{NewAccount.id} to 001xxx"]
    H --> I{Subrequest 2<br/>succeeds?}

    I -->|Yes| J["Continue to subrequest 3..N<br/>(resolve references as needed)"]
    I -->|No, allOrNone=true| K["ROLLBACK entire transaction<br/>All previous subrequests undone"]
    I -->|No, allOrNone=false| L["Log failure for subrequest 2<br/>Continue to subrequest 3"]

    J --> M["All subrequests processed"]
    M --> N["Return single response<br/>hasErrors flag + per-subrequest results"]
    K --> N
    L --> J

    style K fill:#ffcdd2
    style N fill:#e8f5e9

Behavior	allOrNone = true	allOrNone = false
Transaction scope	All subrequests share one transaction	Failed subrequests do not roll back previous successful ones, but all subrequests execute within the same request context (not separate database transactions)
On failure	Entire request rolls back	Only failed subrequest rolls back
Reference IDs	Resolved sequentially	Resolved sequentially (but failed refs cause downstream failures)
Use case	Parent-child record creation where all must succeed	Independent operations where partial success is acceptable
Governor limits	Shared across all subrequests	Shared across all subrequests

Reference ID dependency chains

If subrequest 2 references the ID from subrequest 1, and subrequest 1 fails with allOrNone=false, subrequest 2 will also fail because the reference cannot be resolved. Design your subrequest order carefully and always place dependent operations after their prerequisites.

When to Use

• Creating related records in a single transaction
• Reducing API call consumption (1 call instead of 25)
• Mobile apps where network round trips are expensive
• When operations have dependencies on each other

---

Pub/Sub API (gRPC)

The modern, high-performance event streaming API. Uses gRPC protocol with Avro-encoded events. Replacement for the legacy Streaming API.

Key Characteristics

• gRPC-based bidirectional streaming
• Avro binary encoding (compact, schema-enforced)
• Subscribe to Platform Events, Change Data Capture, and custom channels
• Publish and subscribe capabilities
• Supports managed subscriptions with server-side cursor tracking

Architecture

flowchart LR
    subgraph Publishers
        SF[Salesforce Triggers/Flows]
        EXT[External Publisher]
    end

    subgraph "Salesforce Event Bus"
        EB[Event Bus<br/>gRPC Endpoint]
    end

    subgraph Subscribers
        SUB1[External Subscriber 1]
        SUB2[External Subscriber 2]
        SUB3[Apex Trigger Subscriber]
    end

    SF -->|Publish| EB
    EXT -->|Publish via gRPC| EB
    EB -->|Stream| SUB1
    EB -->|Stream| SUB2
    EB -->|Deliver| SUB3

When to Use

• High-throughput event consumption from external systems
• When you need managed subscriptions (server tracks position)
• Modern event-driven architectures
• Replacing legacy CometD/Bayeux Streaming API

When NOT to Use

• Simple, low-volume polling (REST API query is simpler)
• If gRPC is not supported in the client environment
• Batch data synchronization (use Bulk API)

---

Streaming API (Legacy)

CometD/Bayeux long-polling protocol for receiving near-real-time notifications. Being superseded by Pub/Sub API.

Channels

Channel Type	Purpose	Example
PushTopic	SOQL-based record change notifications	New high-value Opportunities
Generic Streaming	Custom event broadcasting	Application-specific events
Platform Events	Custom business events	OrderPlaced, PaymentReceived
Change Data Capture	Standard/custom object changes	Any field change on Account

Migration path

PushTopics and Generic Streaming Events are in maintenance mode. For new implementations, use Pub/Sub API with Platform Events or Change Data Capture. The CTA board may still ask about Streaming API for legacy scenarios.

---

GraphQL API

Lets consumers request exactly the data they need in a single query, avoiding over-fetching and under-fetching.

Key Characteristics

• Single endpoint: /services/data/v60.0/graphql
• Queries and mutations (mutations GA in API v66.0, Spring ‘26)
• Supports SOQL-like filtering and relationship traversal
• Ideal for mobile and bandwidth-constrained clients

When to Use

• Mobile applications needing optimized payloads
• Complex queries spanning multiple related objects
• When consumers need flexible, self-service data access
• Reducing the number of API calls for related data

When NOT to Use

• Bulk data operations
• When consumers are WSDL-based legacy systems

---

Metadata API & Tooling API

Metadata API

• Deploy and retrieve metadata (custom objects, fields, layouts, etc.)
• Used by Salesforce CLI, VS Code extensions, CI/CD pipelines
• SOAP-based (with REST Metadata API for some operations)
• Not for data operations — for org configuration only

Tooling API

• REST and SOAP access to metadata for developer tooling
• Supports SOQL against metadata types (ApexClass, ApexTrigger, etc.)
• Used for: code compilation, debug logs, test execution, code coverage
• Lighter-weight than Metadata API for specific use cases

---

API Selection Decision Flowchart

flowchart TD
    A[What do you need to do?] --> B{Data or Metadata?}
    B -->|Metadata| C{Deploy/Retrieve?}
    C -->|Deploy| D[Metadata API]
    C -->|Query/Tooling| E[Tooling API]
    B -->|Data| F{Volume?}
    F -->|High: thousands+| G[Bulk API 2.0]
    F -->|Low-Medium| H{Direction?}
    H -->|Flexible schema| I[GraphQL API<br/>Queries + Mutations]
    H -->|Standard CRUD| K{Protocol constraint?}
    H -->|CRUD| K
    K -->|SOAP/WSDL required| L[SOAP API]
    K -->|No constraint| M{Multiple operations<br/>in one call?}
    M -->|Yes| N[Composite API]
    M -->|No| O[REST API]
    F -->|Event-driven| P{Event type?}
    P -->|Data changes| Q[Change Data Capture]
    P -->|Custom business events| R[Platform Events]
    P -->|External high-throughput| S[Pub/Sub API gRPC]

---

Rate Limits Summary

Limit Type	Value	Applies To
Daily API requests	Varies by edition (100K-500K base)	REST, SOAP, Composite, Bulk
Concurrent API requests (long-running)	25	All APIs
Bulk API daily batches	15,000	Bulk API 2.0
Streaming API concurrent clients	2,000	Streaming/Pub/Sub
Platform Events published per hour	Varies by allocation	Platform Events
Composite subrequests	25 per request	Composite API
sObject Collections	200 records per request	Collections API
API request timeout	120 seconds	All synchronous APIs
Callout timeout (Apex)	Default 10s per callout, configurable up to 120s; 120s cumulative per transaction	Apex HTTP callouts

API limit exhaustion

Running out of daily API calls is a production emergency. In CTA scenarios, always design with API limit budgeting: estimate daily call volume, compare to allocation, and build in headroom. If the math does not work, use Bulk API, Composite API, or change the pattern to reduce call volume.

---

API Authentication

OAuth Flow	Use Case	Involves User?
Web Server Flow	User-facing applications	Yes
JWT Bearer Flow	Server-to-server, automated	No (service account)
Device Flow	Input-constrained devices	Yes (out-of-band)
Client Credentials Flow	Machine-to-machine (no user context)	No
Username-Password Flow (deprecated)	Legacy scripts (avoid in new designs)	No (but insecure)

Named Credentials

Always recommend Named Credentials for Salesforce-initiated callouts. They handle token management, refresh, and credential storage securely. Hardcoding credentials or storing tokens in custom settings is an anti-pattern the board will challenge.

---

CTA Scenario Tips

• Count your API calls: For every integration, estimate daily API consumption and compare against limits
• Composite for efficiency: If a process requires 5 API calls, ask whether Composite can reduce it to 1
• Bulk for volume: Any time data volume exceeds a few thousand records, the answer is almost always Bulk API 2.0
• Pub/Sub for events: For real-time event-driven architectures, Pub/Sub API is the modern choice
• GraphQL for mobile: When a mobile or SPA frontend needs flexible data, GraphQL reduces over-fetching
• Named Credentials always: There is no acceptable reason to hardcode credentials in a CTA scenario

---

Related Content

• Large Data Volumes — Bulk API 2.0 selection and volume thresholds are driven by LDV considerations
• Shield & Encryption — API access to encrypted fields and Shield Platform Encryption impact on API behavior
• Platform Capabilities — API limits are governed by edition, license type, and org-level platform limits

---

Sources

• Salesforce API Overview (Official)
• Salesforce REST API Developer Guide
• Composite API Documentation
• Composite Request Body Reference
• Bulk API 2.0 Developer Guide
• Pub/Sub API Developer Guide
• Salesforce API Limits
• Trailhead: API Basics
• Salesforce Architect: API Strategy