A practical guide for Salesforce architects: understand the API landscape, choose the right API for each use case, and design integrations that scale securely across the enterprise.
What this guide covers
This post explains the key Salesforce APIs — from REST and SOAP to Streaming, Metadata, and Einstein — and shows when to use each. It also highlights best practices and real-world examples to help architects design reliable, scalable integrations.
What is an API in Salesforce?
An API (Application Programming Interface) is a contract that defines how systems communicate with Salesforce. Instead of handling internal data storage or processing, APIs expose operations (create, read, update, delete) so external systems can interact with Salesforce in a controlled way. Think of an API as a menu: you place an order without going into the kitchen.
Core API categories
1. Core Data Access APIs
These APIs are used to access and manipulate record data.
- REST API — Lightweight and easy to use for web and mobile applications. Use for CRUD operations and when you need quick, stateless access.
- SOAP API — WSDL-based, strongly typed, and suited to enterprise systems that require contract-driven integrations (e.g., core banking systems).
- Bulk API (v1 & v2) — Designed for large-volume data loads. Use v1 when you need batch-level control; choose v2 for simplicity and speed with large file uploads.
- GraphQL API — Query exactly the fields you need across multiple objects in a single request, reducing chattiness for front-end or mobile apps.
2. Event-Driven & Streaming APIs
Event-driven integration patterns keep systems synchronized in near real-time and reduce polling.
- Platform Events — Custom business events to notify systems or trigger internal Apex/Flow listeners.
- Change Data Capture (CDC) — Publish record create/update/delete events automatically for reliable synchronization.
- PushTopic — Query-driven topics for real-time notifications on specific changes.
- Generic Events — Reusable events for cross-system signaling that aren’t tied to a single object.
3. Specialized APIs
- Metadata API — Manage and deploy org configuration like objects, fields, layouts, and permission sets. Essential for CI/CD and automating deployments.
- Tooling API — Programmatic access to development and debugging artifacts (Apex classes, logs, components).
- Connect REST API — Access Chatter, feeds, files, and social collaboration features.
- Apex REST — Create custom REST endpoints with Apex for bespoke business logic.
4. Analytics & AI APIs
- Analytics REST API — Automate dataset refreshes, query lenses, and embed dashboards programmatically.
- Einstein Vision & Language — Add image recognition, intent classification, sentiment, and NER without building your own ML models.
5. Industry & Business APIs
Salesforce offers specialized APIs for industry clouds and products such as CPQ & Billing, Marketing Cloud, and Commerce Cloud — each with its own patterns and constraints.
Best practices for API-driven integrations
- Match the API to the use case: use Bulk APIs for mass data loads, Streaming APIs for real-time sync, and Metadata API for deployments.
- Design for resilience: implement retries with exponential backoff, idempotency, and dead-letter handling.
- Secure everything: use OAuth, Named Credentials, CSP where applicable, and enforce least privilege.
- Monitor and alert: track API usage, error rates, latency, and implement alerting for SLA violations.
- Document an API selection matrix: map business scenarios to recommended APIs and patterns.
Real-world scenarios
Example: Use Bulk API v2 to import millions of marketing leads, set up CDC to push customer updates to an ERP, and use Platform Events to orchestrate order processing across services.
Conclusion
APIs are the backbone of scalable integrations. A clear API strategy—choosing the right API, securing it, and building resilient patterns—lets Salesforce serve as a central, reliable integration hub for the enterprise. Architects who master these choices enable faster innovation, lower operational risk, and better customer experiences.
Why this matters for Salesforce admins, developers, and business users: APIs enable automation, data consistency, and real-time workflows that reduce manual work, improve decision-making, and create connected customer experiences.