I'm in the process of pushing some updates to some code I originally wrote 12-18 months ago, and the API Version is between 27.0 and 29.0

I know this is to protect the integrity of the test classes you've built (in case they have changed some things) but is there a best practice around either leaving these alone or trying to keep them up-to-date (maybe just once a year instead of at each release)?

3 Answers 3


It's more beneficial to think of API version as an all-or-none upgrade. Even though all code should be interchangeable, in reality, things tend to break if you have version skew. For example, some versions of JSON encode null values, others don't. Some fields available in 28.0 and above will crash code that's version 27.0 and lower, in some cases (such as this relatively famous bug). Some objects aren't available in some versions of the code.

It's better to be at one solid version (e.g. all code at 24.0), rather than having code that varies wildly from 20.0 to 34.0. Avoid blindly updating everything without first researching all breaking changes. Make a backup of your code and/or plan to revert everything if you decide to upgrade and things break. Make sure you have unit tests for all your classes, and that those unit tests run at the same version as your classes.

On the other hand, if something works the way you expect in code that's versions older than what you have, then leave it at that version until you need to make a fix, introduce an update, etc. If it's working now, odds are it will keep working for the foreseeable future. However, all bets are off if you start using a newer version in newer classes, which may cause the older classes to behave incorrectly. This goes doubly so for utility classes that may be used in many different classes with many different versions. Keep them at the older version, or plan on updating every class that uses the utility class at the same time. Test thoroughly.

Try to bump up all your classes at once, and just one version at a time. It's far easier to research breaking changes between one version than 10 versions. Make sure you perform a Run All Tests afterwards, and be sure you have good unit tests (those that include asserts), rather than code coverage unit tests. If you've been in the habit, now would be a good time to catch up.

  • really like your mentality! it seems ideal to optimise for managing those changes incrementally and intentionally, but also good not to be a complete slack ass and leave behind in the dust things that would become expensive surprises after too long. very balanced, thanks for articulating :-) Commented Mar 27, 2015 at 13:51
  • all good points, thanks for explaining your mentality... i like the philosophy... Commented Mar 27, 2015 at 14:20
  • @sfdcfox The LastViewedDate issue is still preventing us from moving some code to prod to this day...quite frustrating.
    – JCD
    Commented Apr 20, 2016 at 15:34
  • @JCD Try moving all your classes everywhere to v28, as that might help you. Do make sure to "run all tests" and validate that this doesn't break anything first, of course.
    – sfdcfox
    Commented Apr 20, 2016 at 15:38
  • Thanks for the suggestion; we unfortunately have ~200 classes on v27 or lower, and don't have the resources to do full regression on the entire org. Our change sets with LastViewedDate validate and deploy fine, but then other unrelated code in the org (v28+) immediately begins failing at runtime with some pre-compilation error about there not being a LastViewedDate field. I've never seen a version discrepancy with Apex that was quite this pesky.
    – JCD
    Commented Apr 21, 2016 at 14:24

My general approach is to try to keep them as up to date as possible. The only real "breaking" change I have observed is from 23 to 24, when they changed default SeeAllData behavior to false. Just run your tests immediately afterward, and if they fail...you have some work to do or you can just revert to an earlier API. Most of the time it is very low risk.

  • Thanks. Is there any particular benefit to doing this? Or is it just an OCD kind of thing? Commented Mar 26, 2015 at 16:03
  • 1
    If you are really OCD, you can stay on top of it, yes. I think the benefit is just that you would find those "breaking changes" sooner, and you can then just dive in and add the newest functionality without needing to worry about API Version because it's up to date. I only update it on files I am working with.
    – Adrian Larson
    Commented Mar 26, 2015 at 16:05
  • 3
    Depends on your code. 27 to 28 had some breaking changes, 32 to 33 had some breaking changes, and so on. If you're not using the features that had breaking changes, then upgrading is fairly risk-free. But it's worth noting that you shouldn't necessarily change it "just because" you're in the class. Utility classes are more likely to break a large number of other classes at once.
    – sfdcfox
    Commented Mar 26, 2015 at 16:31
  • Yes I appreciate your wisdom in this arena.
    – Adrian Larson
    Commented Mar 26, 2015 at 16:33

Had a similar experience when using a different version of API to the WSDL API version being used. Best is to use the API version with which our classes are built.

However as per Salesforce Salesforce strives to make backward compatibility easy when using the Force.com platform.

Each new Salesforce release consists of two components:

A new release of platform software that resides on Salesforce systems
A new version of SOAP API

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .