API Selection: Quick Reference
Every Salesforce API at a glance with rate limits, volume thresholds, and authentication flows. For full details, see Salesforce API Landscape Deep Dive.
API Selection Cheat Sheet
| API | Protocol | Format | Volume | Best For |
|---|---|---|---|---|
| REST API | REST | JSON | Low-med (1-200 records) | Default for CRUD, modern integrations |
| SOAP API | SOAP | XML | Low-med | Legacy WSDL systems, Partner WSDL |
| Bulk API 2.0 | REST | CSV/JSON | High (2K-100M records/24h) | Large data loads, migrations, batch sync |
| Composite API | REST | JSON | Low-med (25 subrequests) | Multi-step ops, reducing round trips |
| sObject Collections | REST | JSON | Up to 200 records | Bulk CRUD on same object type |
| sObject Tree | REST | JSON | Up to 200 records | Creating parent-child record trees |
| Pub/Sub API | gRPC | Avro | Event-based | High-throughput event streaming (strategic) |
| Platform Events API | REST | JSON | Event-based | Custom business events |
| Change Data Capture | Pub/Sub | Avro | Event-based | Automatic data change notifications |
| GraphQL API | GraphQL | JSON | Low-med | Flexible queries, mobile optimization |
| Metadata API | SOAP/REST | XML/JSON | N/A | Deployments, org configuration |
| Tooling API | REST/SOAP | JSON/XML | N/A | Dev tools, IDE, code analysis |
| Apex REST/SOAP | REST/SOAP | JSON/XML | Low-med | Custom business logic endpoints |
API Decision Flowchart
flowchart TD
A[What do you need?] --> B{Data or Events<br/>or Metadata?}
B -->|Metadata| C[Metadata API / Tooling API]
B -->|Events| D{Data changes<br/>or business events?}
D -->|Data changes| E[Change Data Capture]
D -->|Business events| F[Platform Events]
D -->|External subscriber| G[Pub/Sub API - gRPC]
B -->|Data CRUD| H{How many records?}
H -->|"1-200"| I{Multiple related<br/>ops in one call?}
I -->|Yes| J[Composite API]
I -->|No| K{Need flexible<br/>query shape?}
K -->|Yes| L[GraphQL API]
K -->|No| M[REST API]
H -->|"200-2K"| N[sObject Collections<br/>or Bulk API 2.0]
H -->|"2K+"| O[Bulk API 2.0]
style M fill:#e8f5e9
style J fill:#e8f5e9
style O fill:#fff3e0
style E fill:#e3f2fd
style F fill:#e3f2fd
style G fill:#e3f2fd
Rate Limits — The Numbers You Must Know
Daily API Request Limits
| Edition | Base Allocation (24h) | Per-User Addition |
|---|---|---|
| Enterprise | 100,000 | +1,000 per SF license, +200 per other |
| Unlimited | 500,000 | +1,000 per SF license, +200 per other |
| Performance | 500,000 | +1,000 per SF license, +200 per other |
API limit math at the board
Always show the math. Example: “With 500 Salesforce licenses on Unlimited, we have 500,000 base + 500,000 user = 1,000,000 daily calls. Our integration uses 200,000/day, leaving 80% headroom.” If the math does not work, redesign with Bulk API, Composite, or event-driven patterns.
Critical Limits Table
| Limit | Value | Why It Matters |
|---|---|---|
| Daily API calls | 100K-500K base (by edition) | Exceeding = production outage |
| Concurrent long-running calls | 25 (5 for dev org) | Calls > 20s count; most overlooked limit |
| Apex callout timeout | 120s max per callout (10s default, configurable via setTimeout), 120s cumulative per transaction | Request-Reply default is 10s — increase with setTimeout when needed |
| Composite subrequests | 25 per request | Use to consolidate 25 calls into 1 |
| sObject Collections | 200 records per request | Quick bulk CRUD without Bulk API overhead |
| Bulk API daily batches | 15,000 | Rarely hit but plan for high-frequency jobs |
| Bulk API max file size | 150 MB per upload | Split large files if needed |
| Bulk API max records/24h | 100 million | Partition very large migrations across days |
| Bulk Query result size | 15 GB per job | Large exports may need multiple queries |
| Streaming/Pub/Sub concurrent clients | 2,000 | Scale subscriber architecture accordingly |
| Platform Events per hour | Varies by entitlement | Enterprise Plus: 500K+ daily |
| Platform Event retention | 24h standard / 72h high-volume (standard-volume being retired; new events are high-volume by default) | Events gone after retention window |
| CDC retention | 3 days | Subscriber down > 3 days = events lost |
| API request timeout | 120 seconds | Long-running sync calls risk this limit |
Volume Decision Thresholds
| Records per Transaction | Recommended API |
|---|---|
| 1-25 | REST API (individual calls or Composite) |
| 25-200 | sObject Collections or Composite Batch |
| 200-2,000 | Bulk API 2.0 (serial) or sObject Collections |
| 2,000-100,000 | Bulk API 2.0 (serial mode) |
| 100,000-10M | Bulk API 2.0 (parallel mode) |
| 10M+ | Bulk API 2.0 + partitioned jobs + off-peak |
Serial vs Parallel Bulk API
Use serial mode when loading parent-child data or when records share lock contention (e.g., all Contacts under the same Account). Parallel mode causes “UNABLE_TO_LOCK_ROW” errors. This is a frequent CTA scenario trap.
Event Technology Comparison
| Feature | Platform Events | CDC | Pub/Sub API | Streaming (Legacy) |
|---|---|---|---|---|
| Schema | Custom-defined | Mirrors object | Subscribes to PE/CDC | SOQL-based |
| Publish | Apex, Flow, API | Automatic on DML | gRPC | Automatic |
| Subscribe | Apex Trigger, Flow, LWC, API | Same as PE | gRPC (external) | CometD |
| Retention | 24h / 72h (HV) | 3 days | Per event type | None |
| Delivery | At-least-once | At-least-once | At-least-once | At-most-once |
| Status | Strategic | Strategic | Strategic | Maintenance mode |
| External publish? | Yes | No | Yes | No |
| Field change tracking? | Manual | Automatic | Via CDC channel | SOQL-defined |
Quick rule: CDC vs Platform Events
CDC = “What data changed on this record?” (automatic, field-level tracking) Platform Events = “Something business-meaningful happened” (custom semantics like OrderSubmitted, PaymentFailed) They are not mutually exclusive — use both when the scenario calls for it.
Authentication Flows — Quick Pick
| Scenario | OAuth Flow | User Context? |
|---|---|---|
| Server-to-server (default for integrations) | JWT Bearer | Service user |
| User-facing web app | Web Server (Auth Code) | Yes |
| Machine-to-machine, no user context | Client Credentials | No |
| Input-constrained device (IoT, TV) | Device Flow | Yes (out-of-band) |
| Legacy scripts (avoid in new designs) | Username-Password (deprecated) | No (insecure) |
Named Credentials — always
Always recommend Named Credentials for Salesforce-initiated callouts. They handle token management, refresh, and secure storage. Hardcoding credentials or storing tokens in Custom Settings is an anti-pattern the board will challenge. For the new model, use External Credentials with Named Credentials for multi-protocol auth support.
Integration Security
| Concern | What to Know |
|---|---|
| mTLS / Certificate Auth | Mutual TLS — both sides present certificates. Required in banking, healthcare, and government integrations. Configure via Salesforce certificate management. |
| External Credentials | New model replacing legacy Named Credentials. Separates authentication (External Credential) from endpoint (Named Credential). Supports OAuth, JWT, custom headers, and AWS Signature. |
| IP Allowlisting | Lock Connected Apps to specific IP ranges. Combine with OAuth scopes for defense-in-depth. |
| Shield Encrypted Fields | Encrypted fields return masked values in API responses unless the caller has the “View Encrypted Data” permission. Plan for this in integration design — downstream systems may receive masked data unexpectedly. |
External Credentials at the board
If the scenario mentions Named Credentials, clarify whether it is the legacy model (single object) or the new model (External Credential + Named Credential). The new model is the strategic direction and supports per-user or per-named-principal authentication. Always recommend the new model for greenfield designs.
Reverse-Engineered Use Cases
Scenario 1: E-Commerce Order Sync
Situation: Shopify processes 50,000 orders/day. Each order needs to create an Account, Contact, Order, and 3 Order Items in Salesforce. Real-time not required — hourly sync is acceptable.
What you’d present:
- API: Bulk API 2.0 (50K records/day is well above REST threshold)
- Mode: Serial (parent-child: Account —> Contact —> Order —> Order Items)
- API budget: 4 Bulk API jobs/hour x 24h = 96 daily batches (well under 15K limit)
- Auth: JWT Bearer flow, dedicated integration user
- Error handling: Partial failure handling — success records commit, failed records retry next cycle
Scenario 2: Real-Time Credit Check
Situation: Loan officers need instant credit scores when creating Opportunity. External credit bureau responds in 600ms. 200 checks/day.
What you’d present:
- API: REST callout from Apex (Request-Reply pattern)
- Timeout: 600ms well within 10s limit
- API budget: 200 calls/day is negligible vs. allocation
- Auth: Named Credentials with External Credential (OAuth to credit bureau)
- Fallback: Circuit breaker in Platform Cache; if bureau down, show “credit check pending” and queue for retry
Scenario 3: Customer Portal with Live Updates
Situation: Customer portal must show case status changes within 10 seconds. 5,000 active portal users, approximately 2,000 case updates/hour.
What you’d present:
- Event tech: Change Data Capture on Case object (automatic, field-level tracking)
- Subscriber: Pub/Sub API (gRPC) for high-throughput external consumption
- Why not polling: 5,000 users polling every 10s = 1.8M API calls/hour (impossible)
- Why CDC over PE: Case status is a data change, not a custom business event
- Recovery: If subscriber down > 3 days, run batch reconciliation job via Bulk API 2.0
Composite API Variants — Quick Pick
| Variant | Max Records/Subrequests | Dependencies? | Use Case |
|---|---|---|---|
| Composite | 25 subrequests | Yes (reference results) | Create Account, then Contact referencing Account ID |
| Composite Batch | 25 subrequests | No (all independent) | Multiple independent operations |
| sObject Tree | 200 records | Parent-child | Create Account with child Contacts/Opps in one call |
| sObject Collections | 200 records | No | Bulk update 200 records of same type |