REST (Representational State Transfer)
REST (Representational State Transfer) is the architectural style for web APIs that organizes operations as HTTP verbs (GET, POST, PATCH, DELETE) applied to resource URLs (/Account/001..., /Opportu…
Definition
REST (Representational State Transfer) is the architectural style for web APIs that organizes operations as HTTP verbs (GET, POST, PATCH, DELETE) applied to resource URLs (/Account/001..., /Opportunity/006...) and exchanges data in lightweight formats like JSON. Salesforce exposes one of the most-used enterprise REST APIs in the world, with stable endpoints versioned by URL (vXX.X) and authentication through OAuth 2.0 access tokens.
REST is the modern alternative to SOAP, the SOAP-and-XML-based protocol Salesforce shipped earlier and still supports. REST is preferred for almost every integration today because the payloads are smaller, the URLs are human-readable, the authentication flow plugs cleanly into OAuth 2.0, and tools like curl, Postman, and any HTTP client library work without specialized WSDL generation. Salesforce REST endpoints cover CRUD on every standard and custom object, composite operations, bulk data, query, search, metadata, and an ever-growing list of feature-specific APIs.
Why REST became the default integration shape for Salesforce
Resource-oriented URLs
REST treats every Salesforce record, object, and operation as a resource with a stable URL. /services/data/v62.0/sobjects/Account is the Account object resource. /services/data/v62.0/sobjects/Account/0014x000004Pq1q is one specific Account record. /services/data/v62.0/query?q=SELECT+Id+FROM+Account is a query result resource. The HTTP verb on each URL determines the operation: GET reads, POST creates, PATCH updates, DELETE removes. This pattern makes the API immediately legible to anyone who knows HTTP, which is the entire point of REST as a design style.
Versioning by URL
The Salesforce REST API encodes the version in the URL path (/services/data/v62.0/...). Each release cycle introduces a new version while keeping every prior version working. Customers can pin their integration to a known version and upgrade on their own schedule. The version is also visible in every request, which makes operational debugging easier: a logged 401 on v45 is unambiguous about which API surface the caller was using. Salesforce supports a generous deprecation window before retiring old versions, typically 3 to 5 years from release.
JSON as the default payload
REST request and response bodies are JSON by default. A POST to create an Account looks like { Name: "Acme Inc", Type: "Customer", Industry: "Manufacturing" }. The response includes the new record's ID and a success flag. Smaller payloads compared to SOAP XML, easier to inspect with curl or Postman, and trivial parsing in JavaScript, Python, or any modern language. Salesforce also supports XML payloads on the same endpoints by setting the Accept header, but JSON is the path almost every customer uses.
Authentication and OAuth 2.0
Every REST call carries an OAuth 2.0 access token in the Authorization header (Bearer abc123...). The token is issued by the Salesforce OAuth endpoints (/services/oauth2/token, /services/oauth2/authorize) and ties the call to a Connected App and a user identity. Tokens are short-lived (default 2 hours) and paired with a refresh token for long-lived integrations. The OAuth flow plugs into standard libraries (axios, requests, fetch) without bespoke code, which is one of the practical reasons REST beats SOAP for customer-built integrations.
Composite and Bulk REST
Beyond single-record CRUD, Salesforce exposes Composite REST (multiple operations in one HTTP call) and Bulk REST (asynchronous batch operations on millions of records). Composite is for chaining several related calls (create an Account and its primary Contact in one transaction). Bulk is for ETL-style data loads with chunked CSV or JSON upload, asynchronous processing, and a results endpoint to poll. Both endpoints follow the same authentication model and version path as the main REST API.
Rate limits and pagination
Every Salesforce org has an API daily limit (calculated by edition and user count) and a 24-hour rolling window. The REST API includes the remaining call count in the Sforce-Limit-Info response header on every call. Pagination on query results uses a nextRecordsUrl link in the response body; the client follows the link to retrieve the next page. The platform also rate-limits per concurrent call, and the response includes a 429 status with Retry-After header when the client should back off.
REST vs SOAP: when each makes sense
REST wins for almost every modern integration: web apps, mobile apps, server-to-server, partner integrations. SOAP retains a small footprint in legacy enterprise integrations that already speak SOAP (BizTalk, older WebMethods, certain financial systems) and in cases where the Salesforce SOAP API exposes a feature the REST API has not caught up on. Salesforce maintains feature parity between the two as much as possible, but new APIs are increasingly REST-first; SOAP is preserved for backward compatibility rather than for new functionality.
Make your first authenticated REST call against Salesforce
Stand up a Connected App, get an OAuth access token, and run a GET on the sobjects endpoint to confirm the Salesforce REST API is reachable from your environment.
- Create a Connected App
Setup, App Manager, New Connected App. Enter the name, contact email, and callback URL. Enable OAuth Settings and add the scopes (Api, Refresh Token, Full).
- Save and note the credentials
Save the Connected App. Copy the Consumer Key and Consumer Secret from the new app's detail page. These are the client_id and client_secret for the OAuth flow.
- Request an access token
Run curl -X POST https://login.salesforce.com/services/oauth2/token with grant_type=password, client_id, client_secret, username, and password+security_token. The response contains the access_token.
- Discover the API base URL
The token response includes an instance_url. The REST API base is instance_url plus /services/data/v62.0. Set this as your API root.
- Run a test query
curl -H "Authorization: Bearer ACCESS_TOKEN" "https://INSTANCE/services/data/v62.0/query?q=SELECT+Id,Name+FROM+Account+LIMIT+5". Confirm you receive a JSON response with the expected accounts.
- Inspect the rate-limit header
The response includes a Sforce-Limit-Info header showing api-usage. Log this in your integration so you can alert when usage approaches the org cap.
The Salesforce object that holds OAuth credentials, callback URL, and scopes for an external integration.
The authentication flow used to get an access token (Web Server, User Agent, JWT Bearer, Refresh Token, Username-Password).
The version path segment in the URL. Pin to a known version, upgrade on your own schedule.
Bundle multiple REST calls into one HTTP request. Reduces round-trips and supports per-call rollback.
- Password OAuth flow requires the username, password, and security token concatenated as one string in the password parameter. Missing the token returns INVALID_LOGIN with no useful detail.
- Access tokens expire after the session timeout (default 2 hours). Long-running integrations must use the refresh token to obtain new access tokens without re-authenticating the user.
- The API daily limit is per org, not per Connected App. A misbehaving integration can exhaust the org cap and lock out other integrations.
- REST endpoints differ from SOAP in some edge cases (the upsert payload shape, the way binary attachments are handled). Always test your specific endpoint, not just the documented common cases.
Trust & references
Cross-checked against the following references.
- REST API Developer GuideSalesforce Developer Docs
- REST API Quick StartSalesforce Developer Docs
- Connected App OverviewSalesforce Help
Straight from the source - Salesforce's reference material on REST (Representational State Transfer).
- REST API DocumentationSalesforce Developer Docs
- Bulk API DocumentationSalesforce Developer Docs
- Composite REST ResourceSalesforce Developer Docs
Hands-on resources to go deeper on REST (Representational State Transfer).
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 REST?
Q2. What HTTP methods does REST use?
Q3. What data formats does Salesforce REST API use?
Discussion
Loading discussion…