HTTP API Contract

Compatibility

The commercetools platform uses continuous delivery to be able to deploy updates multiple times a day. This means that we don't have fixed release cycles, but instead release features as soon as they are ready. It also allows us to correct any possible issues very fast. Nevertheless, keeping track of all improvements and changes might not be possible for all users at all times. Thus, we ensure that:

• No values or fields will be changed or deleted in an API unless it is published as a named new version.
• Every change within the same API version only includes additional information:
  • new fields and values within an existing object
  • new API endpoints
  • required fields becoming optional

Implications

Please be aware that if a client sends additional undocumented fields, these can conflict with future new platform field names, causing runtime errors. Avoiding this is in the responsibility of the client.

SSL/TLS Lifetime

To keep connections to the API secure at all times, it is necessary to periodically renew SSL/TLS certificates and also replace them when adapting to newer security policies. We try to keep those modifications to a minimum. In general, we target a maximum of one certificate renewal per year. However, if security issues are found within any aspect of the encryption algorithms in use, we reserve the right to replace certificates more often.

Release life cycle

Closed beta

After being initially deployed, new features can go through a closed beta phase for evaluation by selected customers. The purpose is to collect feedback early in the development cycle, and improve and refine the new feature. Please consider participating only if you are able to invest some time into feedback sessions with us. Closed beta features must not be used in production. APIs can still change, and in rare cases functionality might be discontinued. Closed beta features do not have publicly available documentation or release notes. We will notify participants of changes.

Public beta

Some new features are tagged as BETA in the documentation. This means that the APIs related to that feature can be subject to change or discontinuation:

• breaking changes are announced three months in advance
• removals are announced six months in advance

Announcements are done through release notes.

Public beta APIs are robust and secure implementations and can be used in production. They receive support and bug fixes like general availability features, but are not covered by Service Level Agreements. Specific security measures can differ from the documented security measures.

General availability

Once a feature is no longer tagged as BETA, it becomes generally available. The change in status is announced in the release notes.

Deprecation

As the commercetools platform evolves, some features are superseded by better implementations and should not be used anymore. The goal of the deprecation process is to communicate with users at runtime if they use deprecated features. To achieve this in a non breaking fashion, the commercetools platform uses an additional custom HTTP header called X-DEPRECATION-NOTICE with a specific message relative to the deprecation.

Example:

"X-DEPRECATION-NOTICE" : "The usage of lower-cased search on variants.price.currencyCode is deprecated"

Limits

To assure good performance for every project on the platform, the API imposes limits on certain parameters and objects. A detailed list of imposed limits can be found here.

Past Changes

• August 2021
  • Renamed chapter from "Versioning" to "Compatibility"
  • Added section about release life cycle
  • moved platform limits to extra page
  • removed redundant mention of Messages API
• May 2018
  • Added explicit warning concerning additional fields

Learn More

For more information, see this blog post.