REST API
The Salesforce REST API is the platform's primary HTTP-based programmatic interface for reading and modifying Salesforce data and metadata from external systems.
Definition
The Salesforce REST API is the platform's primary HTTP-based programmatic interface for reading and modifying Salesforce data and metadata from external systems. It exposes every standard and custom sObject through resource-oriented URLs, returns JSON payloads, supports the standard HTTP verbs (GET, POST, PATCH, DELETE), and authenticates via OAuth 2.0 through a Connected App. Mobile apps, integration platforms, custom web apps, ETL tools, and AI assistants all reach into Salesforce through this API.
The REST API is versioned (currently in the 60s), with each version pinned by the URL path: /services/data/v60.0/sobjects/Account. Newer versions add features and refine behavior; older versions stay available for backward compatibility. The API supports composite calls (multiple sub-requests in one HTTP roundtrip), batch operations (up to 25 sub-requests in parallel), tree creation (parent and children in one request), query (SOQL via the query endpoint), search (SOSL), bulk operations (delegated to Bulk API), and resource discovery. For most integrations, REST API is the modern default; SOAP API remains for legacy patterns that REST does not cover.
How the Salesforce REST API connects external systems
Authentication via OAuth and Connected Apps
Every REST API call needs an OAuth access token obtained through a Connected App. The standard flows: Web Server (user redirects through a consent screen), JWT Bearer (signed JWT from the integration), Client Credentials (service account without user), Refresh Token (renew an existing session). The access token attaches to each API call as the Authorization: Bearer header. Token lifetime, scope, and refresh behavior are configured on the Connected App and the External Credential. Mishandling token storage is the most common security incident pattern for REST API integrations.
Resource model and endpoint structure
Every Salesforce object is a resource at /services/data/vXX.X/sobjects/ObjectName. GET retrieves records, POST creates, PATCH updates, DELETE removes. Specific records use /sobjects/ObjectName/RecordId. The describe endpoint (/sobjects/ObjectName/describe) returns metadata about fields, relationships, and constraints. Composite calls bundle multiple resource operations into one HTTP request to reduce round trips. Query and Search endpoints support SOQL and SOSL respectively. The full URL structure makes integration code resource-oriented and discoverable.
Composite, batch, and tree operations
For multi-step workflows, REST API supports three composition patterns. Composite chains multiple sub-requests where later steps reference earlier results (insert an Account, then insert a Contact pointing at the new Account ID). Batch runs up to 25 independent sub-requests in parallel within one HTTP call. Tree creates a parent and its children in one transaction (insert an Account with five Contacts in one POST). Each reduces API call counts and improves performance compared to separate requests. Composite is the most powerful and the one most modern integrations use.
Query, Search, and the explorer endpoints
The Query endpoint executes SOQL via GET /services/data/vXX.X/query?q=SELECT+Id+FROM+Account. Pagination uses the nextRecordsUrl link in the response. The Search endpoint runs SOSL similarly. The Limits endpoint returns current API consumption against daily limits, useful for monitoring. The Tooling API has its own REST surface for querying metadata objects (ApexClass, EntityDefinition, FieldDefinition) that the standard API does not expose directly. The User Interface API serves Lightning-component-style data shaped for UI consumption.
Bulk API: when REST is the wrong tool
REST API is interactive and per-record. For bulk data loads (over 50,000 records, ETL jobs, data migration), Bulk API 2.0 is the right tool. REST API caps at small batch sizes per request (200 records in composite tree). Bulk API processes thousands of records per minute in chunked jobs. The two APIs share authentication and resource model but optimize for different use cases. Most integrations use REST for interactive operations and Bulk for batch loads.
Governor limits, rate limiting, and daily API caps
Every org has a daily API call cap based on edition and license count (typically tens of thousands to millions of calls per day). REST API consumption counts against this cap. Rate limiting also applies at the per-second level to prevent overload. The Limits endpoint returns current consumption; Setup > API Usage shows historical data. Build retry logic with exponential backoff for transient 503 responses, and monitor consumption to avoid blowing the daily cap during peak periods.
Versioning and forward compatibility
The API version is pinned in every URL: /services/data/v60.0/sobjects/Account. Salesforce ships a new version each major release. Old versions stay available for backward compatibility (typically the last 7 to 10 years of versions). Best practice: pin integration code to a specific version, upgrade deliberately during planned maintenance, test against the new version before flipping. Letting versions drift produces subtle behavior changes that surface as production bugs months later.
How to call the Salesforce REST API
Calling the Salesforce REST API from an external system has three layers: authenticate via OAuth, construct the request URL with the right API version and resource, and handle the response with proper error handling. Build with a tested client library (Salesforce ships SDKs for Node, Python, Java, .NET) rather than rolling raw HTTP; the SDKs handle authentication, retries, and pagination consistently.
- Create a Connected App for OAuth
Setup > App Manager > New Connected App. Configure OAuth with the right flow (JWT Bearer for server integrations, Web Server for user-facing). Note the Consumer Key and Consumer Secret. Pre-authorize the right profiles or permission sets.
- Obtain an access token
Make a POST to /services/oauth2/token with the OAuth grant parameters. The response includes access_token (used in subsequent API calls), instance_url (the base URL for API calls), and refresh_token (used to renew without re-authenticating).
- Construct the API call URL
Use the instance_url and the API version: https://yourdomain.my.salesforce.com/services/data/v60.0/sobjects/Account. Append /RecordId for specific records, /describe for metadata, or use /query?q=SOQL for SOQL queries.
- Add the Authorization header
Every request needs Authorization: Bearer ACCESS_TOKEN. Without it, the API returns 401. Tokens expire (typically 2 hours); handle 401 by refreshing the token and retrying.
- Send the request and parse the response
Use the appropriate HTTP verb (GET, POST, PATCH, DELETE) with JSON body for write operations. The response is JSON. Check the HTTP status code and the response body for errors. 2xx responses are success; 4xx are client errors; 5xx are server errors.
- Handle pagination for query results
Large query results return a nextRecordsUrl field. Make a GET to that URL to retrieve the next page. Repeat until the response indicates done=true. Most SDKs handle pagination automatically.
- Implement retry with exponential backoff
Transient errors (503, 504, rate limit responses) should be retried with exponential backoff. Permanent errors (400, 404) should not retry. Build retry logic into the integration layer so callers do not have to handle it.
- Monitor API consumption
Call the Limits endpoint periodically to track daily API consumption. Setup > API Usage shows historical patterns. Alert when consumption approaches the daily cap so you can investigate spike causes before hitting the limit.
Web Server, JWT Bearer, Client Credentials, or Refresh Token. Drives how the integration obtains access tokens.
Pinned in the URL path. Pin to a specific version for stability; upgrade deliberately during planned maintenance.
Patterns for bundling multiple operations into one HTTP request to reduce round trips and API consumption.
- REST API call counts against the daily API cap. High-volume integrations can blow the cap during peak periods. Monitor consumption and rate-limit upstream callers if needed.
- Tokens expire after the configured lifetime. Implement refresh token handling; 401 responses without retry logic produce intermittent integration failures.
- API version pinning is required for stable integrations. Letting the URL drift to whatever version Salesforce currently serves produces subtle behavior changes as versions release.
- REST API is per-record. For bulk operations over 50,000 records, switch to Bulk API 2.0. REST batch operations cap at 25 sub-requests per call.
- Connected App secrets must be stored in a secrets manager, never embedded in client code or version control. Leaked Consumer Secrets are the most common Salesforce credential incident.
Related free tool
Trust & references
Cross-checked against the following references.
- REST API Developer GuideSalesforce Developer
- Composite REST APISalesforce Developer
- REST API Query EndpointSalesforce Developer
Straight from the source - Salesforce's reference material on REST API.
- REST API DocumentationSalesforce Developer
- REST API Quick StartSalesforce Developer
- OAuth Quick StartSalesforce Developer
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is Salesforce REST API?
Q2. What's a Composite request?
Q3. What URL pattern does REST API use?
Discussion
Loading discussion…