Mastering Salesforce APIs: Composite vs. Bulk API 2.0 vs. GraphQL

⚡ 1-Minute Summary
The Salesforce platform offers specialized APIs for different workloads. The Composite API bundles multiple REST calls into a single trip. Bulk API 2.0 processes millions of records asynchronously. GraphQL allows front-end applications to query exact data fields to avoid over-fetching. Choosing the wrong API leads to poor performance and hitting governor limits.

💬 In plain words:
Three power APIs for three different jobs:
Composite API bundles several REST calls into one single trip (e.g., creating a parent and children in one POST).
Bulk API 2.0 acts like a freight train, moving millions of rows as background jobs.
GraphQL acts like a restaurant menu, letting the caller order exactly the fields it wants with no wasted data.

📌 Example:
Need to create an Account + 3 Contacts + 1 Opportunity in ONE API round trip? Use a Composite request with allOrNone=true so it's an all-or-nothing transaction. Need to run a nightly 5-million row data load? That's what Bulk API 2.0 is built for.

⚙️ Core API Concepts

There are three primary call-in styles, each designed for a specific shape of work in Salesforce:

• Composite REST API: Bundles up to 25 subrequests into a single round trip. It supports reference chaining (e.g., @{ref.id}), meaning you can create an Account and its child Contacts in one call. It can enforce transactional integrity (allOrNone=true), or run independently as a Composite Batch. (Composite Graphs handle even larger data trees).
• Bulk API 2.0: Built strictly for massive volume. You submit a large dataset (like a CSV job), and the Salesforce platform automatically handles chunking and parallel processing internally. This is vastly simpler than the old Bulk V1, which required developers to manage batching manually. You simply monitor the job and fetch failed records when done.
• GraphQL API: Backed by the UI API, this allows a client to query exactly the fields and related data it needs. It supports cursor pagination and prevents custom front-end applications from over-fetching unnecessary data.

🧭 360 Card — Composite, Bulk 2.0 & GraphQL

• Rule: Composite bundles calls into one trip. Bulk handles massive background data. GraphQL requests precise data shapes.
• Gain: Each API solves a specific pain point: excess round trips, volume bottlenecks, and data over-fetching.
• Reach for:
  • Standard REST: For single records.
  • Composite: When a screen needs multiple calls in one trip (up to 25) with atomicity.
  • Bulk API 2.0: The moment your data rows pass a few hundred thousand.
  • GraphQL: When the caller wants to shape its own payload and handle pagination smoothly.
• Price & Limits: Picking the wrong API costs you latency or governor limits. Composite caps at 25 subrequests. Bulk requires you to monitor job status. GraphQL requires modern client-side query structuring.

❓ Core Q&A and Scenarios

Q: An external app needs to create an Account, 3 Contacts, and an Opportunity atomically. Which API and why?

🎯 Say this first:
"Use the Composite API (or Composite Graph)—it allows one call, referenced IDs between subrequests, and the allOrNone flag provides full atomicity."

Detailed Answer: Use Composite REST with allOrNone=true.

• It only requires one round trip. The subrequests can reference the newly created Account dynamically using @{refAccount.id}.
• A failure anywhere rolls the whole set back—perfect for transactional requirements.
• Why not the others? Separate REST calls are chatty, non-atomic, and require complex cleanup logic if a partial failure occurs. Bulk is absurd for just 5 records. A custom Apex REST endpoint is only justified if you have complex, server-side business logic wrapping the creation. Otherwise, stick to out-of-the-box Composite API.

Q: Bulk API 2.0 vs 1.0 — what did 2.0 actually change operationally?

A: Bulk API 1.0 forced the client application to manage the batching. You had to manually split files, submit the batches, and track each one individually.

• Bulk API 2.0 accepts one single job upload. The Salesforce platform handles the chunking and parallelism internally.
• It exposes simple job states and lets you easily retrieve unprocessed or failed records.
• This results in much less client-side code and fewer partial-submission bugs.

⚠ Developer Trap: Bulk Parallel Contention
While Bulk 2.0 handles batching for you, it processes in parallel. If your data involves heavy parent-child relationships (e.g., thousands of contacts linking to one Account), you will hit locking errors. You still must sort and group your CSV data locally before uploading to avoid contention.

Q: The mobile team complains that standard REST forces 6 calls and massive data over-fetching just to paint one UI screen. What are the on-platform options?

A: Use the GraphQL API.

• GraphQL allows a single query that names exactly the fields and related lists required for that specific screen.
• It handles cursor pagination effortlessly and strictly respects Field-Level Security (FLS) and sharing rules, just like the UI API.
• Alternatives: A Composite request could bundle the 6 calls into one trip, but it doesn't fix the over-fetching problem. A custom Apex REST endpoint returning a Data Transfer Object (DTO) is highly efficient, but it creates technical debt because you now have to maintain and version a custom contract for every screen. GraphQL is the modern, scalable choice.

🔑 Key Takeaways

• Never build a custom Apex REST endpoint if Composite API can handle the transaction natively.
• Bulk API 2.0 is the standard for high-volume data movement; let Salesforce handle the chunking, but you must still handle data sorting to prevent locking.
• GraphQL is the premier solution for modern UI clients that need specific, shaped data payloads without making redundant API calls.