Version hygiene is a quiet, ongoing discipline. Done well it pays off invisibly; ignored, it surfaces at the worst possible moment as a forced upgrade or a deprecation outage.
- Inventory current API versions
Query the org's ApexClass and ApexTrigger metadata. Inspect REST callout code and Named Credentials for the version segment. Build a table of which artifacts run at which version.
- Pick a target version
Choose a target API version for the next quarter. Most teams target N-1 or N-2 (one or two releases behind current). Going to N requires testing every new release's behaviour changes.
- Upgrade Apex classes incrementally
Edit metadata to bump apiVersion. Run the test suite per class. Investigate any regressions against the release notes for that version. Promote in stages.
- Update REST and SOAP callers
Update the version segment in callout code and refresh WSDLs for SOAP integrations. Document the new contract for downstream consumers.
- Monitor for deprecation announcements
Subscribe to release notes. Track which API versions are scheduled for retirement and plan the upgrade well before the cutover date.
- apiVersion changes can shift SOQL behaviour, governor limits, and method signatures silently. Test the regression suite after every bump.
- Mixing versions across one project makes triage harder. Pick a target version per release and apply it consistently.
- Staying too far back to avoid one deprecation accumulates years of change into a single forced upgrade.
- Managed package classes carry their own apiVersion. Subscribers cannot edit it; upgrading the package is the only way.