How should you manage the API version of Apex classes in Salesforce?
What is the best practice for managing the API version of Apex classes in Salesforce? When you have older Apex code written 12–18 months ago with API versions between 27.0 and 29.0, should you leave these versions as they are, or should you regularly update them to newer API versions? How often should such updates be performed, and what precautions should a developer take when upgrading the API version?
Managing the API version of Apex classes requires careful consideration. While Salesforce intends API versions to be backward-compatible, in practice, differences between versions can lead to subtle bugs or unexpected behavior. For example, some versions handle JSON serialization of null values differently. Some fields or objects may not be available in older API versions, which could lead to runtime errors if you use them. Additionally, known platform issues exist for specific versions, which might affect your code if it remains outdated.
A recommended approach is to treat API version updates as an all-or-none operation rather than selectively upgrading classes one at a time. Maintaining consistency across your codebase helps prevent “version skew,” where different classes behave inconsistently because they are on different API versions. It is advisable to pick a stable version and gradually upgrade all classes to that version, one step at a time. Jumping multiple versions at once is riskier because it becomes difficult to track breaking changes and resolve issues.
Before upgrading, you should back up all code. This ensures that if an upgrade introduces errors, you can revert to a stable version. Thorough unit testing is critical; make sure that all tests run under the same API version as the classes they cover. Avoid relying solely on code coverage tests; your unit tests should assert expected behavior explicitly. After updating the API version, run all tests to ensure that your changes did not break any existing functionality.
In some cases, leaving classes at their current API version is acceptable, especially if they are stable and functioning correctly. However, if you are introducing new features or classes that rely on newer platform capabilities, older classes may need to be upgraded to ensure compatibility. Special attention should be given to utility classes used by multiple other classes. Upgrading a utility class without upgrading all dependent classes could introduce inconsistencies. Therefore, it is often better to upgrade all dependent classes simultaneously.
Practical Example: Upgrading an Apex Class API Version
Suppose you have a simple utility class written with API version 28.0:
// API Version: 28.0
public class StringUtils {
public static Boolean isEmpty(String input) {
return input == null || input.trim().length() == 0;
}
}
This class works perfectly in your org, but now you want to upgrade it to version 56.0 to leverage newer Salesforce features.
Step 1: Update API Version
In Salesforce, open the class in the Developer Console or VS Code, and change the API version:
// API Version: 56.0
public class StringUtils {
public static Boolean isEmpty(String input) {
return input == null || input.trim().length() == 0;
}
}
Notice that the code itself may not change initially, but the behavior could differ slightly if newer API versions handle certain methods differently (e.g., handling of null values in some methods or stricter SOQL enforcement).
Step 2: Run Unit Tests
Create or update a test class:
@IsTest
private class StringUtilsTest {
@IsTest
static void testIsEmpty() {
System.assertEquals(true, StringUtils.isEmpty(null));
System.assertEquals(true, StringUtils.isEmpty(''));
System.assertEquals(true, StringUtils.isEmpty(' '));
System.assertEquals(false, StringUtils.isEmpty('Hello'));
}
}
Run Run All Tests to validate that the upgraded API version does not break any behavior.
Step 3: Upgrade Dependent Classes
If other classes call StringUtils.isEmpty, ensure that either all those classes are also upgraded to API version 56.0, or test them carefully to avoid unexpected behavior caused by version mismatch.
Step 4: Incremental Upgrades
If your org contains multiple classes with older versions, upgrade them one API version at a time (e.g., 28 → 30 → 32 → … → 56). After each step, run tests and validate functionality. This minimizes risk compared to jumping many versions at once.
Enroll for Career-Building Salesforce Training with 100% Money Back Guarantee
Our Salesforce Course is thoughtfully designed to give you a comprehensive understanding of the Salesforce platform, equipping you with essential skills to excel in the CRM industry. The program covers key modules such as Salesforce Admin, Developer, and AI, blending theoretical knowledge with hands-on practice. Through real-world projects and practical exercises, you’ll gain the expertise needed to solve complex business challenges using Salesforce solutions. Our expert instructors ensure you develop both technical proficiency and industry insights to thrive in the Salesforce ecosystem.
Beyond technical skills, our Salesforce Training in Florida provides personalized mentorship, certification support, and interview coaching to boost your career prospects. You’ll have access to in-depth study materials, real-time project experience, and ongoing guidance throughout your learning journey. By the end of the course, you’ll be well-equipped for certification exams and possess the practical problem-solving skills that employers highly value. Start your Salesforce journey with us today and open the door to exciting career opportunities. Sign up for a Free Demo now!
