Salesforce ships nine different APIs because nine different integration shapes exist. Picking the wrong one means rebuilding your integration when you hit a limit. This pillar maps every API to its right use case, links to deep dives on the trickier ones, and explains the auth + rate-limit rules that apply across all of them.
The nine Salesforce APIs at a glance
| API | Purpose | Format | Async? |
|---|---|---|---|
| REST API | Everyday CRUD, mobile, modern web apps | JSON | Sync |
| SOAP API | Legacy strongly-typed clients (Java, .NET) | XML / WSDL | Sync |
| Bulk API 2.0 | Large data loads / extracts (>10k rows) | CSV/JSON over REST | Async |
| Tooling API | IDE / developer tool integration | REST or SOAP | Sync |
| Metadata API | Org metadata deployments (full packages) | XML over SOAP | Async |
| Streaming API | Push notifications via Bayeux | JSON | Streaming |
| Pub/Sub API | Modern event streaming via gRPC | Protobuf | Streaming |
| Connect REST API | Chatter, Experience Cloud, Files | JSON | Sync |
| Apex REST | Custom endpoints you build in Apex | JSON | Sync |
REST API: the default
If you're starting an integration today, start here. JSON over HTTPS, OAuth 2.0 auth, supports CRUD on every standard and custom object:
curl https://yourinstance.my.salesforce.com/services/data/v62.0/sobjects/Account/001xxxxx \
-H "Authorization: Bearer $ACCESS_TOKEN"
Key endpoints:
/services/data/vXX.0/sobjects/{Object}/{Id}— single record/services/data/vXX.0/query?q=SELECT+...— SOQL/services/data/vXX.0/composite/sobjects— batch up to 200 records/services/data/vXX.0/composite— batch arbitrary REST calls (count as 1 API call)
REST is fastest for under 10,000 records, easiest to debug (curl works), and supported everywhere. For larger volumes, switch to Bulk.
Bulk API 2.0: for big jobs
When you need to load or extract more than 10k records, REST API's per-call limits become painful. Bulk API 2.0 batches into asynchronous jobs:
# Create job
POST /services/data/v62.0/jobs/ingest
{ "object": "Account", "operation": "upsert", "externalIdFieldName": "External_Id__c" }
# Upload data
PUT /services/data/v62.0/jobs/ingest/{jobId}/batches
Content-Type: text/csv
[...CSV body...]
# Mark complete, poll status
PATCH /services/data/v62.0/jobs/ingest/{jobId}
{ "state": "UploadComplete" }
Salesforce processes in 10k-record chunks asynchronously. Doesn't count against synchronous REST limits, supports up to 150 million records per job. The Salesforce CLI's sf data import bulk and Data Loader's Bulk API mode both use this under the hood.
SOAP API: when WSDL is required
If your client is Java EE, .NET WCF, or anything that consumes WSDL files, SOAP is still the simplest fit. There are two WSDLs:
- Enterprise WSDL — strongly typed to your org's metadata (your custom fields are typed). Regenerate after schema changes.
- Partner WSDL — generic SObject types (no custom-field typing). Stable across orgs and schema changes.
Use Enterprise for tight coupling to one org; use Partner for ISV apps that connect to many orgs. Full comparison: Enterprise vs Partner WSDL: Differences.
For new builds, prefer REST unless your tooling specifically demands WSDL — see Salesforce SOAP vs REST for the full decision matrix.
Tooling API: for developer tools
The Tooling API is purpose-built for IDEs and developer-facing tools. It handles individual metadata records (one Apex class, one trigger) without the package overhead of Metadata API:
# Compile a single Apex class
PATCH /services/data/v62.0/tooling/sobjects/ApexClass/{id}
Content-Type: application/json
{ "Body": "...new code..." }
# Execute Anonymous Apex
GET /services/data/v62.0/tooling/executeAnonymous/?anonymousBody=System.debug%28%27hi%27%29%3B
VS Code's Salesforce extension, Workbench's Apex tab, and Illuminated Cloud all use this. Full reference: Salesforce Tooling API: Developer Guide.
Metadata API: for full deployments
When you need to deploy a package of metadata between orgs (a sandbox to production deploy), Metadata API is the right tool. It accepts/returns a zip of XML files describing your metadata. SFDX, Change Sets, and DevOps Center all sit on top of it.
The trade-off: every operation involves a full package retrieve/deploy cycle, which is slow for single-record changes (hence Tooling API for those). Use Metadata API for releases, Tooling API for live edits.
Streaming and Pub/Sub: for real-time events
Two APIs serve push-notification use cases:
- Streaming API (Bayeux/CometD) — older, long-polling, simpler. Push platform events to subscribers.
- Pub/Sub API (gRPC) — modern, bidirectional, supports replay from any position, higher throughput. Recommended for new builds.
Pub/Sub uses Protocol Buffers and gRPC — your client needs the corresponding library (Node, Go, Python, Java all have official bindings). For most use cases, Pub/Sub is the right choice in 2026.
Authentication
OAuth 2.0 in five flows. Pick by your scenario:
| Flow | Use case |
|---|---|
| JWT Bearer | Server-to-server, no human, modern default for backend integrations |
| Web Server | Browser app with redirect callback |
| User-Agent | Pure client-side / mobile |
| Device | IoT, non-browser devices |
| Username-Password | Legacy only — discouraged |
The JWT Bearer flow is the modern default for backend integrations: certificate-based, no refresh tokens to manage, no human login required. Full guide: Salesforce JWT Flow Guide.
Rate limits
Daily per-org API call limit varies by edition:
- Developer Edition: 15,000 calls/day
- Enterprise: ~1 million baseline + scaled by user count
- Unlimited: typically 10x Enterprise
Hitting the limit returns REQUEST_LIMIT_EXCEEDED until the rolling 24-hour window resets. Mitigations:
- Use Composite API to batch multiple REST calls into one (counts as 1 call regardless of inner ops).
- Cache reference data (picklist values, custom metadata) — query once, reuse all day.
- Move bulk operations to Bulk API (separate limit pool).
- Use bulk-aware queries —
WHERE Id IN :idSetreturns N records in 1 call instead of N round-trips.
Deep-dive guides
- Salesforce Tooling API: Developer Guide
- Salesforce SOAP API Guide
- Salesforce SOAP vs REST
- Enterprise vs Partner WSDL: Differences
- Salesforce JWT Flow Guide
- Salesforce API Integration: Architect's Guide
- What is a Salesforce Connected App (the registration step for any API integration)
Common API mistakes
- Using REST for million-row loads. Switch to Bulk API 2.0.
- Hardcoding instance URLs. Always derive from the OAuth response — instance URLs change.
- Forgetting to refresh access tokens. They expire (1-2 hours typical). Use refresh tokens or JWT Bearer flow.
- No retry on 503. Salesforce occasionally throttles — implement exponential backoff.
- Mixing API versions. Stick to one version per integration; upgrade deliberately.
- Username-Password flow in 2026. Deprecated for security — migrate to JWT or Web Server.
Salesforce's API catalog is broader than most platforms' — but each API exists for a reason. Pick by use case (CRUD vs bulk vs tooling vs events), match the auth flow to your deployment model (server vs browser vs device), and respect the rate limits. Done right, you can build integrations that handle millions of records and survive years of org evolution.
Leave a Comment