AJAX Toolkit
The AJAX Toolkit is the JavaScript library Salesforce historically provided so client-side code could call the SOAP API and Apex web service methods directly from the browser.
Definition
The AJAX Toolkit is the JavaScript library Salesforce historically provided so client-side code could call the SOAP API and Apex web service methods directly from the browser. It exposed an sforce.connection object that wrapped login, query, create, update, delete, and Apex web service calls, returning JavaScript objects that pages could render or manipulate. The toolkit shipped as connection.js and apex.js and was loaded from a /soap/ajax/<version>/connection.js URL inside any Visualforce page or S-Control. Developers used it to build server-aware behaviour into Classic pages before Lightning Components or LWC existed.
The AJAX Toolkit is firmly legacy. Salesforce has not added new features to it in over a decade, and the underlying SOAP API path it depends on is itself in maintenance mode. Modern Salesforce code calls the REST API, the User Interface (UI) API, or invokes Apex through @AuraEnabled methods on Lightning Components. The toolkit still loads on Classic surfaces and continues to work in older orgs, but new development is strongly discouraged. Most enterprise orgs have migrated their remaining AJAX Toolkit code as part of the Lightning Experience migration; what remains usually sits inside long-tail Visualforce pages that nobody has rewritten yet.
What the AJAX Toolkit was for, and why nobody writes new code with it
What the toolkit actually did
The toolkit gave browser JavaScript a Salesforce session token plus a wrapper around the SOAP API endpoints. With four or five lines of code, a developer could run a SOQL query, modify the returned records, save them back, and reflect the result on the page without a page reload. That sounds trivial today, but in 2008 it was the difference between an interactive Visualforce page and a clunky postback-driven form.
The sforce.connection object
sforce.connection is the entry point for every API call. After the page loads connection.js, the toolkit calls sforce.connection.init() or inherits the session from the running Visualforce page. From there, methods like sforce.connection.query, sforce.connection.create, sforce.connection.update, and sforce.connection.deleteIds wrap the equivalent SOAP operations. Returned records arrive as JavaScript objects with the same field names as the underlying sObject.
Apex web service calls and apex.js
apex.js extended the toolkit to call public Apex web service methods (methods marked with the legacy webService keyword) by name. The pattern was sforce.apex.execute(className, methodName, parameters). This was the way to put server-side business logic behind a browser action before @AuraEnabled and Apex REST resources existed. Many old packages still depend on webService methods that only the AJAX Toolkit can invoke from a Classic page.
Synchronous versus asynchronous calls
The toolkit supports both. A bare sforce.connection.query(soql) blocks the browser thread until the response returns. Adding a callback object as a second argument switches to async. Most production code used async to avoid freezing the UI, but plenty of older codebases ran synchronous calls because the code looked simpler. Synchronous JavaScript blocks the page render and counts against modern browser deprecation warnings, which is one more reason new code should not use it.
Authentication and session handling
Inside a Visualforce page, the toolkit picks up the session ID and server URL from the page automatically. Outside Visualforce (in a static HTML page or another web app), the toolkit can run sforce.connection.login with a username and password to obtain a session. The login path is one of the strongest reasons not to use the toolkit anymore: storing username and password in client-side JavaScript was always risky, and Salesforce now strongly recommends OAuth flows instead.
Why the toolkit is legacy
Several factors retired the AJAX Toolkit. SOAP was overtaken by REST. Lightning components have @AuraEnabled methods for Apex calls with built-in session handling. The fetch API and modern XHR replaced sforce.connection.query for direct REST work. Browser security tightened around third-party JavaScript loading session tokens. None of these forces eliminated the toolkit overnight, but together they made new investment in it unwise.
Modern alternatives
REST API calls via fetch are the standard for arbitrary backend interaction from a Lightning Web Component. The UI API offers higher-level record-level operations including layout-aware reads. Apex called from a component uses @AuraEnabled methods and the imperative apex import. Each of these is supported, performant, and aligned with current platform guidance. None requires sforce.connection or connection.js.
Migration strategies for surviving toolkit code
Most migrations replace toolkit calls one for one with @AuraEnabled Apex methods called from a Lightning Component. Pages that only queried and displayed data can move to UI API or to Lightning Record View Form with no Apex at all. Tools like Salesforce DX scratch orgs make it cheap to spike a Lightning replacement before retiring the Visualforce surface. Tests written against the old toolkit usually do not survive, but the underlying business logic in Apex web service methods almost always carries over with minor signature changes.
How to retire AJAX Toolkit code
Most orgs do not write new AJAX Toolkit code, but they do hold surviving Visualforce pages that still call it. Retiring those pages is the operational task.
- Inventory remaining toolkit usage
Grep the metadata for sforce.connection and sforce.apex references across Visualforce pages and Static Resources. Document each page, the calls it makes, and the users who land on it.
- Classify each page by complexity
Read-only pages can move to UI API or Lightning Record View Form. Pages with custom server-side logic need an Apex web service method to be replaced with an @AuraEnabled method.
- Build the Lightning replacement
Create a Lightning Web Component or Aura component that performs the equivalent operation. Use @AuraEnabled or imperative Apex for server calls and the modern fetch or UI API for direct record work.
- Route users to the new surface
Update navigation, list view buttons, and any direct URL links so users land on the Lightning page instead of the Visualforce page. Keep the Visualforce page accessible for one release in case rollback is needed.
- Delete the retired metadata
Once the Lightning replacement is stable, remove the Visualforce page, the Static Resource holding connection.js, and any related Apex web service classes that no other code uses.
- The legacy webService keyword on Apex methods is separate from @AuraEnabled. They support different callers; do not remove the keyword on a class still called by an AJAX Toolkit page.
- Toolkit calls inside Static Resources are easy to miss in code search. Look for connection.js references and any inline script blocks that import it.
- Synchronous AJAX Toolkit calls trigger modern browser warnings. Migration removes the noise as a side benefit; do not ignore the warnings until then.
- Sessions obtained via sforce.connection.login require username and password. Refactor to OAuth flows during migration; do not port the password-based code as is.
Trust & references
Cross-checked against the following references.
- AJAX Toolkit Developer GuideSalesforce Developer Docs
- REST API Developer GuideSalesforce Developer Docs
Straight from the source - Salesforce's reference material on AJAX Toolkit.
- User Interface APISalesforce Developer Docs
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. The AJAX Toolkit is a JavaScript wrapper around which Salesforce API?
Q2. Which of the following is the modern recommended alternative to the AJAX Toolkit?
Q3. Where was the AJAX Toolkit traditionally used?
Discussion
Loading discussion…