Salesforce releases are big news, and they bring about new features that make everyone happy. (Check out this recent blog post on my favorite features from the Summer ‘15 Release Notes if you haven’t yet.) These Salesforce releases happen 3 times a year and mean that there is a new API revision for everyone to use. However, the old revisions don’t go away. Salesforce supports these old revisions for the foreseeable future. But, since they are supported and you can keep using them, this can cause issues for orgs that span many revisions.
I’ll throw a situation at you. You hear of a new feature that you want to use, and you put it in old code. And it doesn’t compile. The classes or methods you are trying to use don’t exist. There is a reason for that. Each version of the API only has the features, methods, and classes that it came with when it was released.
New features come out for specific revisions of the Apex API. Classes have to be set to the correct API revision or the features aren’t available for use. When you are starting a new class, it may get the newest revision of the API (depending on how you create it). However, when it comes to old code, you will have to upgrade the API version.
There are a couple ways to upgrade a class to a new revision. The admin UI has a version setting tab on the class itself. And you can edit the metadata in whatever IDE you are using to write the code.
What are the reasons to upgrade?
There are a few times when it probably makes sense to upgrade either all of your classes or at least some specific classes. If you need a new feature that is only available in a more recent revision, then upgrading to the new version makes sense. If a newer class interacts with older classes, you might want to get them all at a specific revision. Or, if any of your code is more than 12 revisions–or 4 years–behind, you should probably upgrade them to a newer version. Generally, you want to keep all of your code at the same version.
Having said all that, sometimes it makes sense to just leave a class alone. Frequently, if it’s not broken, it may not be a bad idea to keep it as is.
With 3 releases per year, classes can get out of date pretty fast. That’s why it’s important to spend just a little bit of time each year examining what versions of the API your classes are using. This can help to avoid problems at the heart of your organization. For example, there are some specific bugs–like this one–that can happen if you have mismatched versions.
We queried a few other people who work with Salesforce, and the responses have been mixed. Andy Mahood feels if it’s not required to update it, leave it alone. Brian Kwong tries to keep things updated. I think Brian said it nicely with “It depends,” but Andy knows one very important truth: “Plan for regression.”
What problems have you had with API classes? Or what reasons have you needed to upgrade your classes? Share your own story with us in the comment section below.