APIs & Integrations

Salesforce API Guide: REST, SOAP, Bulk, Composite, and GraphQL Explained

Share

Salesforce offers a variety of API styles because no two integration scenarios are the same. Some systems need instant, real-time updates. Others deal with huge data volumes. Some workflows demand multi-step transactions, while certain UIs just need a few precisely nested fields.
This guide walks you through the main Salesforce API styles — explaining what each one does, when to use it, and how they compare. You’ll also get quick, copy-ready code snippets and a look at how Graph-style APIs work beyond Salesforce.

1) REST API (sObjects, Query, Search)

Concept:
The REST API follows a resource-based design and uses simple JSON over HTTP. You can use /sobjects for CRUD operations, /query for SOQL queries, and /search for SOSL searches. It’s usually the go-to choice for modern web servers, mobile apps, and backend integrations.

Typical uses:
Real-time data creation and updates, list retrieval, powering Lightning Web Components, or connecting Salesforce with middleware tools.

Trade-offs:
Because each request handles one operation, it can feel “chatty” when you need to make multiple calls in sequence. Also, always remember to respect field-level security (FLS), CRUD rules, and API limits.

Example — GET Account by Id

curl -H "Authorization: Bearer <access_token>" -H "X-PrettyPrint: 1" \
  https://<instance>.my.salesforce.com/services/data/v61.0/sobjects/Account/001XXXXXXXXXXXX

Example — SOQL query

curl -H "Authorization: Bearer <access_token>" \
  "https://<instance>.my.salesforce.com/services/data/v61.0/query?q=SELECT+Id,Name,Industry+FROM+Account+LIMIT+5"

Apex callout pattern (to external REST)

HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint('callout:MyAPI/users?page=1'); // Named Credential recommended
HTTPResponse res = new HTTP().send(req);
System.debug(res.getBody());

2) SOAP API (Enterprise/Partner)

Concept:
SOAP uses an XML-based, contract-first approach with WSDL files. You generate strongly typed Apex classes using “WSDL2Apex.” It’s especially helpful when dealing with older systems or those that require formal, regulated integration standards.

Typical uses:
Integrations with ERP or financial systems, or any system that mandates WS-* contracts.

Trade-offs:
SOAP is more verbose than REST and generally slower to work with from a developer perspective, but it provides a rigid structure ideal for compliance-heavy environments.

Steps:

  1. Download the WSDL file

  2. Generate Apex from WSDL

  3. Add endpoint (Remote Site Setting or Named Credential)

  4. Invoke the generated methods

Example — Apex SOAP call (pattern)

MySoapStub binding = new MySoapStub();
binding.endpoint_x = 'callout:MySoapNamedCred';
CreateCustomerRequest req = new CreateCustomerRequest();
req.name = 'Ada Lovelace'; req.email = 'ada@example.com';
CreateCustomerResponse resp = binding.createCustomer(req);
System.debug(resp.resultCode);

3) Bulk API (v1 & v2)

Concept:
The Bulk API handles large-scale data uploads and extractions asynchronously.

  • Bulk v1: You create a job, upload multiple batches (usually in CSV), and then close the job.

  • Bulk v2: Simplified — create the job, upload data (CSV or NDJSON), mark it complete, and check the results.

Typical uses:
Nightly data synchronization, large data migrations, analytics backfills, or any process involving millions of records.

Trade-offs:
It’s asynchronous only — not designed for interactive, real-time interfaces.

Bulk v2 — Ingest Upsert (CSV)

# Create job
curl -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  https://<instance>.my.salesforce.com/services/data/v61.0/jobs/ingest \
  -d '{"object":"Account","operation":"upsert","externalIdFieldName":"External_Id__c"}'

# Upload CSV
curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: text/csv" \
  --data-binary @accounts.csv \
  https://<instance>.my.salesforce.com/services/data/v61.0/jobs/ingest/<JOB_ID>/batches

# Finalize + poll
curl -X PATCH -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  https://<instance>.my.salesforce.com/services/data/v61.0/jobs/ingest/<JOB_ID> \
  -d '{"state":"UploadComplete"}'
curl -H "Authorization: Bearer <token>" \
  https://<instance>.my.salesforce.com/services/data/v61.0/jobs/ingest/<JOB_ID>

Bulk v1 — Classic pattern (sketch)

# Create job (XML)
curl -H "X-SFDC-Session: <token>" -H "Content-Type: application/xml" \
  https://<instance>.my.salesforce.com/services/async/61.0/job -d \
'<jobInfo xmlns="http://www.force.com/2009/06/asyncapi/dataload">
  <operation>insert</operation><object>Account</object><contentType>CSV</contentType>
</jobInfo>'

# Add batch, then close job similarly

4) Composite & Batch APIs (multi-operation in one call)

Concept:
These APIs let you send multiple REST operations together in a single call. You can even reference previous results within the same request or choose to make the entire operation transactional with the allOrNone flag.

Typical uses:
Creating a parent record and its children in one shot, minimizing API round trips, or running workflows that must either fully succeed or fail as a unit.

Trade-offs:
Payloads are more complex, and error handling can require extra care.

Composite — Create Account then Contact

POST https://<instance>.my.salesforce.com/services/data/v61.0/composite
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/v61.0/sobjects/Account",
      "referenceId": "refAccount",
      "body": { "Name": "Salesforce" }
    },
    {
      "method": "POST",
      "url": "/services/data/v61.0/sobjects/Contact",
      "referenceId": "refContact",
      "body": { "LastName": "Vegi Sreeknath", "AccountId": "@{refAccount.id}" }
    }
  ]
}

Composite Batch — independent calls together

POST https://<instance>.my.salesforce.com/services/data/v61.0/composite/batch
{
  "haltOnError": false,
  "batchRequests": [
    { "method":"GET", "url":"v61.0/sobjects/Account/001..." },
    { "method":"PATCH","url":"v61.0/sobjects/Account/001...","richInput":{"Website":"https://example.com"} }
  ]
}

5) GraphQL & Graph API Awareness

Concept (GraphQL in Salesforce):
GraphQL offers a single endpoint where clients can request exactly the fields and relationships they need. It’s ideal for UIs that would otherwise require multiple REST calls to assemble related data.

Typical uses:
Lightning Web Components, dashboards, or any read-heavy UI that needs nested relationships with minimal latency. GraphQL also enforces field-level security via uiapi.

Trade-offs:
It has its own learning curve — you’ll need to understand schema, resolvers, and query cost controls.

Salesforce GraphQL — example query

curl -X POST https://<instance>.my.salesforce.com/services/data/v61.0/graphql \
  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
  -d '{"query":"query { uiapi { query { Account(first:5) { edges { node { Id Name Industry Contacts(first:2){ edges { node { Id Name Email } } } } } } } }"}'

Graph API awareness (outside Salesforce, e.g., Microsoft Graph)

Think of Microsoft Graph as a RESTful API built around tightly linked resources — users, groups, files — accessible via parameters like $select or $top.

Tiny example — get current user

curl -H "Authorization: Bearer <ms_access_token>" \
  https://graph.microsoft.com/v1.0/me?$select=id,displayName,mail

That’s useful context when you’re integrating Salesforce with Microsoft 365 ecosystems.

Short Real-World Scenario (end-to-end sketch)

  • A UI needs a customer snapshot with top contacts → use GraphQL (uiapi) to fetch nested data in one go.

  • A checkout flow calls a payment service and shows the result → do a REST callout using a Named Credential.

  • A nightly process pushes 2M invoices to or from a data lake → go with Bulk API v2 for ingestion or extraction.

  • Onboarding needs to create an Account and Contact atomically → use the Composite API with allOrNone:true.

  • A legacy ERP system still depends on SOAP → the WSDL2Apex class will handle the createCustomer operation.

REST_SOAP_Bulk

Final Thoughts

Each Salesforce API pattern serves a different purpose depending on your latency, data volume, and integration complexity.

  • Use REST for everyday CRUD operations and real-time queries.

  • Use Composite or Batch to bundle multiple calls or enforce atomic transactions.

  • Choose Bulk v2 for massive data transfers, or Bulk v1 when older tooling requires it.

  • Use GraphQL for modern, efficient UI reads with nested data.

  • Stick with SOAP when working with strict, contract-driven systems.

In practice, most mature Salesforce implementations blend two or three of these APIs to cover nearly all integration use cases—balancing performance, scalability, and reliability.

 

  • October 22, 2025

Tags:

You may also like...

Categories