Compatibility Modes
Compatibility mode refers to a B2C Commerce API version that includes changes that affect backward compatibility with the previous API version.
Not every API version affects backward compatibility, so only some API versions have a compatibility mode. API versioning enables you to actively select from multiple compatibility modes, with the full knowledge and acceptance of incompatible changes. The ability to select the compatibility mode you want to use enables you to maintain your customizations on a previous compatibility mode, while B2C Commerce introduces new functionality in one or more newer compatibility modes.
Selectable compatibility modes are newer than the active compatibility mode, in addition to the previously active compatibility mode. You can't select a compatibility mode that is older than the previously active one.
B2C Commerce supports a single active compatibility mode; and maintains a reference to the previously active compatibility mode, to which you can revert, if necessary.
The complete list of compatibility modes available at any time consists of:
- The currently active compatibility mode
- The previously active compatibility mode
- Any new compatibility modes you can activate
When your system was initially provisioned, the active compatibility mode was set to the latest (or most recent) compatibility mode. For example, if you initially provisioned with version 2.10.6, then the active compatibility mode is 2.10.6 because 2.10.6 introduced a corresponding 2.10.6 API version (compatibility mode).
You can specify how many code versions to retain. The oldest, except for the active and previously active code versions, are automatically removed by B2C Commerce (Sandboxes only).
API Documentation
A single API documentation set describes multiple compatibility modes at the class and method level, and potentially multiple compatibility modes for certain methods.
When Do You Need to Change Your Application?
Before activating a new compatibility mode, it's important that you understand the behavioral changes the new mode brings. If the change impacts your application, you might need to modify your application to make it function correctly with the changes and then test. You can only roll back to the previously active compatibility mode if your code is compatible with the old mode (API version). If you write code that takes advantage of the API of a newer version that is incompatible with the old version, you can only roll back if you also revert the respective code.
When using API versioning, you must pay close attention to certain situations:
- All cartridges in an application must use the same active compatibility mode.
- There can be only one active compatibility mode at a time (no wildcard support).
- You can change the compatibility mode on all instances, but we don't recommend that you change the mode directly on Production.
- Avoid using different compatibility modes on Staging and Production.