Salesforce ships nine different APIs because nine different integration shapes exist. Pick the wrong one and you rebuild the integration the day you hit its limit. This page maps every API to its use case, links to deep dives on the trickier ones, and covers the auth and 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"
The endpoints you will actually use:
/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. Bulk jobs don't count against synchronous REST limits, and one job takes up to 150 million records. 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 is strongly typed to your org's metadata, so your custom fields come through typed. Regenerate it after schema changes.
- Partner WSDL uses generic SObject types with no custom-field typing, so it stays 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. Salesforce SOAP vs REST has the full decision matrix.
Tooling API: for developer tools
IDEs and developer-facing tools are what this one is built for. It handles individual metadata records, one Apex class or 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) is older, long-polling and simpler. It pushes platform events to subscribers.
- Pub/Sub API (gRPC) is the modern one: bidirectional, replay from any position, higher throughput. Recommended for new builds.
Pub/Sub uses Protocol Buffers and gRPC, so your client needs the corresponding library (Node, Go, Python and 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 |
JWT Bearer is certificate-based, has no refresh tokens to manage and needs no human at a login screen, which is why it is the default for backend work. 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:
- Batch multiple REST calls into one with the Composite API. It counts as 1 call regardless of inner ops.
- Cache reference data such as picklist values and custom metadata. Query once, reuse all day.
- Move bulk operations to Bulk API, which draws on a separate limit pool.
- Write 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. Derive them from the OAuth response, because instance URLs change.
- Forgetting to refresh access tokens. They expire, typically in 1-2 hours. Use refresh tokens or the JWT Bearer flow.
- No retry on 503. Salesforce throttles occasionally, so implement exponential backoff.
- Mixing API versions. Stick to one version per integration and upgrade deliberately.
- Username-Password flow in 2026. It is deprecated for security reasons, so migrate to JWT or Web Server.
Salesforce's API catalog is broader than most platforms', and every API in it 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.
Leave a Comment