REST API Patterns

REST API Patterns

Use this skill when the integration task involves calling the Salesforce REST API to read, create, update, or delete records, or when you need to compose multiple REST operations efficiently. This skill covers the standard sObject resources, SOQL query resources, the Composite family of resources, and the pagination and error handling patterns that hold an integration together in production.

Before Starting

Gather this context before working on anything in this domain:

• What OAuth 2.0 flow is in use and is a valid access token available? Every REST call requires Authorization: Bearer <token>.
• What Salesforce edition is the target org? API limits (24-hour rolling limit) differ by edition — Developer Edition is 15,000 per day; Enterprise Edition is 1,000 per Salesforce license per day with a minimum of 1,000.
• What API version should be used? Always use a recent version (Spring '25 = v63.0). Old versions are eventually deprecated and unsupported. The base URL is /services/data/vXX.0/.
• What is the record volume per call? Use REST Composite (≤ 25 subrequests), sObject Tree (≤ 200 records), or Bulk API 2.0 (> 2,000 records) accordingly.

Core Concepts

Base URL and Versioning

All REST API resources are relative to the instance base URL and include the API version:

https://<instance>.salesforce.com/services/data/v63.0/

Always pin the version explicitly. Unversioned or pinned-to-old-version calls risk hitting deprecated behavior after a Salesforce release upgrade.

Authentication: OAuth Bearer Token

Every REST request must include the access token in the HTTP Authorization header:

Authorization: Bearer <access_token>

The token is obtained via an OAuth 2.0 flow (Username-Password, JWT Bearer, Web Server, or Device). The Connected App must be configured with the appropriate OAuth scope (api, full, or a more targeted scope). Tokens expire; integrations must handle 401 responses and refresh or re-authenticate.

sObject CRUD Resources

Standard create/read/update/delete operations target the /sobjects/ resource family:

A successful create returns HTTP 201 with a JSON body containing {"id": "...", "success": true, "errors": []}. A successful update or delete returns HTTP 204 with no body.

SOQL Query Resource and Pagination

Execute SOQL via the /query/ resource:

GET /services/data/v63.0/query/?q=SELECT+Id%2CName+FROM+Account+LIMIT+200

If the result set is larger than the batch size (default 2,000 records), the response includes "done": false and a "nextRecordsUrl" field:

{
  "totalSize": 5800,
  "done": false,
  "nextRecordsUrl": "/services/data/v63.0/query/01gXXXXXXXXXXXX-2000",
  "records": [...]
}

Fetch subsequent pages by making a GET request to the absolute path given in nextRecordsUrl (prepend the instance host). Continue until "done": true. Do not attempt to reconstruct the query locator URL manually — use the value exactly as returned.

Composite Resource

The /composite/ resource executes up to 25 subrequests in a single HTTP round trip. Subrequests are ordered and results from earlier subrequests can be referenced in later subrequests using @{referenceId.fieldName} syntax.

{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Account/",
      "referenceId": "NewAccount",
      "body": { "Name": "Acme Corp" }
    },
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Contact/",
      "referenceId": "NewContact",
      "body": {
        "LastName": "Smith",
        "AccountId": "@{NewAccount.id}"
      }
    }
  ]
}

When allOrNone is true, any single subrequest failure rolls back all subrequests in the call. When false, each subrequest result is independent.

Composite Batch Resource

The /composite/batch/ resource executes up to 25 independent subrequests. Unlike /composite/, subrequests cannot reference each other's results. Each subrequest result is independent regardless of the haltOnError flag.

Use Composite Batch when:

• Requests are logically independent (no parent-child ID wiring)
• You want to reduce HTTP round trips for unrelated operations

sObject Tree Resource

The /composite/tree/{SObject}/ resource inserts up to 200 records in a single call, including parent-child related record trees:

POST /services/data/v63.0/composite/tree/Account/

Up to 5 levels of nesting are supported. All records in the tree are committed atomically — partial success is not available. Records across the tree count toward the total 200-record limit.

Error Response Format

When a request fails, Salesforce returns an array of error objects:

[
  {
    "message": "Required fields are missing: [Name]",
    "errorCode": "REQUIRED_FIELD_MISSING",
    "fields": ["Name"]
  }
]

Composite responses embed a httpStatusCode per subrequest alongside the error array. Always inspect individual subrequest bodies when using Composite or Composite Batch — an HTTP 200 outer response does not mean all subrequests succeeded.

Common Patterns

Composite Insert: Account with Related Contact

When to use: You need to create a parent Account and a child Contact in the same transaction without two round trips and without knowing the Account ID in advance.

How it works: Use /composite/ with allOrNone: true. Set a referenceId on the Account subrequest and reference it in the Contact subrequest using @{refId.id}. The platform resolves the reference server-side before executing the Contact insert.

Why not the alternative: Two separate REST calls require the caller to persist the Account ID between calls and handle partial failure (Account created, Contact failed) with compensating logic. The composite approach keeps both in a single atomic transaction.

Paginated SOQL Query Loop

When to use: Any query against a large data set where the result count may exceed 2,000 records.

How it works: Issue the initial /query/ request. If done is false, read nextRecordsUrl from the response and issue a GET to that URL (prefixed with the instance hostname). Repeat until done is true. Buffer or stream records per page — do not assume all records fit in memory.

Why not the alternative: Setting an arbitrarily large LIMIT in SOQL does not bypass the batch size; the API still paginates. Ignoring nextRecordsUrl silently drops records — a hard-to-detect data integrity problem.

Upsert by External ID

When to use: An external system owns a record identifier and you want to create-or-update without first querying for the Salesforce ID.

How it works: PATCH to /sobjects/{SObject}/{ExternalIdField}/{value}. If no record with that external ID exists, Salesforce creates it (HTTP 201). If one exists, Salesforce updates it (HTTP 200). The External ID field must be defined on the object and indexed.

Why not the alternative: A query-then-insert-or-update pattern doubles round trips and introduces a race condition between the read and the write.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

• API version is pinned to a recent version (v60.0+) in all endpoint URLs.
• Authorization: Bearer <token> is present on every request; 401 is handled with refresh logic.
• Paginated queries check done flag and follow nextRecordsUrl until true.
• Composite requests inspect per-subrequest httpStatusCode — outer HTTP 200 is not sufficient.
• allOrNone setting on Composite requests is an explicit architectural choice, not a default.
• Record volume per call is within limits: ≤ 25 subrequests for Composite/Batch, ≤ 200 records for sObject Tree.
• Daily API limit is estimated against the org edition and load tested before go-live.
• Error responses parse the [{message, errorCode, fields}] array; generic string matching on HTTP status is not enough.
• External ID fields used for upserts are defined, indexed, and not shared across integration systems.

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. HTTP 200 outer response masks subrequest failures in Composite — When using /composite/ or /composite/batch/, the outer HTTP response code is 200 even if individual subrequests return 4xx. Integrations that only check the outer status silently discard errors.

2. nextRecordsUrl is not a full URL — it is a path — The value returned in nextRecordsUrl is a relative path like /services/data/v63.0/query/01gXXX-2000. You must prepend the instance hostname. Treating it as a complete URL or re-constructing it from the query locator ID causes 404s or incorrect page fetches.

3. API version deprecation is gradual but permanent — Salesforce deprecates old REST API versions approximately every three years. Integrations pinned to old versions (e.g., v20.0–v40.0) stop working when the version is retired, with no runtime warning. Always pin to a version within the last four releases.

4. Concurrent API request limits are separate from daily limits — Salesforce enforces a limit on concurrent long-running API requests (default 25 per org for calls exceeding 20 seconds). Polling integrations and batch scripts that hold long-running REST calls open can hit this ceiling independently of the daily limit.

5. sObject Tree is all-or-nothing at 200 records — Unlike Composite with allOrNone: false, the sObject Tree resource does not support partial success. One invalid record in the tree rolls back the entire payload. Validate records client-side before sending large trees.

Output Artifacts

Related Skills

• integration/graphql-api-patterns — use when the consumer needs flexible field selection from a single endpoint rather than fixed CRUD resources.
• integration/oauth-flows-and-connected-apps — use when the authentication setup, Connected App scoping, or token refresh flow is the actual blocker.
• apex/apex-rest-services — use when the org needs a custom command API exposed over REST, not a caller consuming the standard REST API.
• data/bulk-api-and-large-data-loads — use when record volumes exceed 2,000 per operation and Bulk API 2.0 async job patterns are needed.