Salesforce REST API: Complete Guide
Quick Summary:
The REST API is Salesforce's primary interface for external applications to read, create, update, and delete data over standard HTTP, using JSON. It's the default choice for most modern integrations.
What Is the Salesforce REST API?
The REST API lets external applications interact with Salesforce data and metadata over standard HTTP requests, using JSON as the primary data format. It's the go-to choice for web applications, mobile apps, and most modern integration patterns, favored over SOAP API for its simplicity and lighter payload size.
Common Endpoint Patterns
| Endpoint Pattern | Purpose |
|---|---|
| /sobjects/{object}/ | List available fields, describe object metadata |
| /sobjects/{object}/{id} | Retrieve, update, or delete a specific record |
| /query/?q={SOQL} | Run a SOQL query and return matching records |
| /composite/ | Batch multiple operations in one request |
How to Get Started
Set up a Connected App to obtain OAuth credentials for authentication.
Authenticate to obtain an access token, using your preferred OAuth flow.
Make an authenticated request to a resource endpoint, including the token in the Authorization header.
Parse the JSON response and handle any errors returned in the response body.
Sample Authenticated Request
GET /services/data/v60.0/sobjects/Account/001XXXXXXXXXXXX Host: yourinstance.salesforce.com Authorization: Bearer [access_token]
A Real-World Example
A custom web portal needs to display a customer's Account details and recent Cases in real time. Rather than syncing data on a schedule, the portal calls the REST API directly whenever a customer logs in, querying for the Account and related Case records and rendering them immediately -- always showing current data rather than a potentially stale sync.
🚫 Common Mistake
Making one API call per record in a loop instead of using the Composite API or batching queries. This burns through API call limits far faster than necessary and is significantly slower than a properly batched request.
💡 Pro Tip
Always specify a fixed API version in your integration rather than defaulting to the latest -- Salesforce releases new versions three times a year, and an unpinned integration can behave unexpectedly after a platform upgrade.
Frequently Asked Questions
Do I need a Connected App to use the REST API?
Yes, for OAuth-based authentication (the standard approach), a Connected App defines the client credentials and permitted scopes for API access.
What\'s the base URL format for Salesforce REST API calls?
Typically https://[your-instance].salesforce.com/services/data/v[version]/ followed by the specific resource path, like /sobjects/Account/.
Can I query records using SOQL through the REST API?
Yes, via the /query endpoint, which accepts a SOQL query string and returns matching records in JSON format.
What authentication methods does the REST API support?
OAuth 2.0 (multiple flow types) is standard; Session ID-based authentication also works but is less common for production integrations.
Is there a rate limit on REST API calls?
Yes, subject to your org's overall API request limits (which vary by edition and licenses), tracked per 24-hour rolling period.
Can the REST API create and update multiple records in one call?
Yes, via the Composite API or the sobjects collections resource, letting you batch multiple operations into a single HTTP request rather than one call per record.
What format does the REST API return data in?
JSON by default, though XML is also supported for most endpoints if specifically requested.
How do I find the current REST API version number?
Query the versions endpoint (/services/data/) without specifying a version, which returns all available API versions for your org.
Can the REST API access custom objects and fields?
Yes, custom objects and fields are fully accessible via the same REST API patterns as standard objects, using their API names (ending in __c).
What\'s the difference between REST API and SOAP API?
REST API is lighter-weight, JSON-based, and generally preferred for modern web and mobile integrations; SOAP API is XML-based and remains common in older enterprise integration patterns.