OCAPI Versioning and Deprecation Policy

This document describes the versioning and deprecation policy for the Open Commerce API (OCAPI). This policy is designed to

  • Be easy for customers and developers to understand
  • Allow Commerce Cloud Digital to make design changes to the API without affecting existing client applications
  • Allow Digital to delete outdated or unsupported features

A new OCAPI version is created whenever Digital:

  • Adds a new document property, resource parameter, or resource.
  • Modifies the type of a document property, resource parameter, or resource.
  • Modifies the name of a document property, resource parameter, or resource.
  • Deletes a document property, resource parameter, or resource.

Whenever Digital creates a new OCAPI version, it also deprecates the former OCAPI version. This encourages customers and developers to:

  • Implement new client applications on top of the current OCAPI version.
  • Upgrade existing applications on a regular basis.

Digital constructs OCAPI version numbers by taking the last two digits of the current year ("13" for 2013), adding a period (.), and adding consecutive numbers, starting with 1. For example, "13.1" is the first version of 2013.

Depending on the context, the version number is specified differently:

  • In URLs, the following syntax is used: v<year>_<consecutive number>. For example: "v13_1".
  • In documents, the following syntax is used:<year>.<consecutive number>. For example: "13.1".
Version StateSupportDescription
CurrentYesThe newest version. Always develop new applications using the current version. Commerce Cloud ensures that an OCAPI version is supported for at least two years. During this period Digital ensures the stability and backwards-compatibility of the version enclosed feature set.
DeprecatedYesDigital deprecates an OCAPI version when a new version is published. Support, stability, and backwards-compatibility are ensured for up to two years after the publish date.
ObsoleteNoDeprecated versions become obsolete automatically two years after being published. Digital deletes obsolete versions without further notice.

OCAPI version metadata currently provides a list of flat version numbers. To better reflect the version life-cycle, the version metadata will be enhanced as follows:

  • A state enum will be added with the following values: current, deprecated, obsolete

Digital notifies customers about new and deprecated versions on the XChange portal and in the Digital Release Notes.