Legacy versions of Open Commerce API (OCAPI) Retirement

Salesforce B2C Commerce includes a REST API layer called the Open Commerce API (OCAPI) that can be used by developers to access B2C Commerce features and functions. With each release of B2C Commerce, a new version of the API is created. These releases occur 8 - 10 times a year. Version numbers are created using the last two digits of the year (17, 18, 19, etc.) and the number of the release (18.1, 18.2, 18.3, etc.). Versions currently exist in the platform back to 2013, starting with v13.6.

As more versions are continually added, older versions become more and more obsolete. Customers need to adopt new versions as much as possible to achieve the benefits of continual cloud software delivery, such as better security, performance, and features. While we understand that adopting every version as it is released is not practical, at the same time, using versions that are multiple years old is also a concern.

OCAPI has a versioning and deprecation policy that can be viewed in the OCAPI documentation. APIs go through three lifecycle states: current, deprecated, and obsolete. Up to this point in time, obsolete versions have never been removed, but that will change starting in July 2020. Versions will reach their end-of-life on the following timelines:
 

• v13 EOL in July 2020 with the B2C Commerce 20.7 release
• v14 EOL in September 2020 with the B2C Commerce 20.9 release
• v15 and v16 EOL in March 2021

Why did we retire these versions?

Maintaining the older codebase results in increased build time and testing time for the overall OCAPI product. The result is that the continual improvement of the product becomes more and more difficult with the existing versions. We want to keep the versions that we support in good shape, with compatibility and a full suite of testing before every release, but continuing that for multiple years of versions is not practical.

There is also security and performance concern. Security issues that are discovered must be addressed in multiple versions, which can cause delays in releasing an issue. Lower priority security issues might only be fixed in newer versions, leaving some low-risk items in the older codebase. From a performance perspective, we are constantly evolving our performance based on the results that we see in production. After every holiday season, some reviews occur to determine how best to improve our capacity and prepare for upcoming holiday seasons. Making these changes across multiple versions is not always possible. This often results in the best performance of the OCAPI requests coming from the newest versions.

In general, as with all development activities, it is best practice to continually update and adopt newer versions of tools and APIs that you might be using.

What happened at the End of Life date?

When a version reaches its end of life, it will be removed from the B2C Commerce code base. API requests made to a version that is EOL will return an HTTP 403 Forbidden response - with a fault type of ClientAccessForbiddenException.

How can I tell if my code was using these older versions?

OCAPI responses come with a header parameter of x-dw-version-status. This parameter will have one of three values: current, deprecated, or obsolete. Developers can inspect these responses for any that return a value of "obsolete" and investigate further if the API calls are v16.x or older.

Salesforce can also provide customers with a list of v16.x and older endpoints that are being called from a given production realm. This information will also include the Client ID value used in the calls. To get this information, please contact your Customer Success Manager.

What action did I need to take?

If you are accessing these older endpoints, then engagement with your development teams to find the calls within your codebase will need to be done. Developers will need to find where the calls are being made by searching for the older version numbers, searching for the usage of the identified Client IDs, or a general search for the endpoint usage.

Once the API calls are found, developers can easily change the calls to later versions of the API. Salesforce would suggest adopting the latest version of the API at the time the changes are made (i.e. change to 20.x). Once changes are made, then run your suite of tests to determine the effects that the change might have on your commerce site(s) and apps. Full regression tests related to the changed areas of code would be suggested.

Once testing is completed and verified, then the customer can coordinate the updates to their production systems through their usual production update processes.

What happens if the action is not taken?

After the End of Life date passes and the older APIs are removed from the B2C Commerce platform, any calls made to those APIs will fail with the error response mentioned above. This response will likely result in customer-developed code failing if it is still making these calls. Customers should review their version dependencies before the end-of-life date is reached to resolve the issue and move to newer versions.

When did we retire the other versions?

We are focused on versions 16x and older. However, we intend to have a regular cadence of old version removal. Timelines for removing the 17.x version have not yet been set, but it would be no earlier than the summer of 2021. Customers can plan as needed, and as more information becomes available, the timeline announcement will be made.

If you have more questions, open a case with Support via Salesforce Help. To view all current and past feature retirements, see Salesforce Active Product & Feature Retirements.

To read about the Salesforce approach to retiring products and features, read our Product & Feature Retirement Philosophy.