HTTP API CONTRACT

As new features are released regularly for the commercetools platform we have an API contract to ensure a smooth evolution. This document presents the different contracts of the API.

Versioning

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 bring features for you live 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 our users at all times. Thus, we ensure as part of our API contract that:

For more information, see this blog post.

Last update: 27/01/2017

Beta features

Some features are tagged as beta. This means that the APIs related to that can be affected to changes and they should be used carefully in production, but are nevertheless stable and can be used to play around or test new functionalities. During the beta phase, feedback is highly appreciated as it helps to iron out all problems and make sure that the feature is really useful. Once the feature is no longer tagged as such, we will announce it 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 our deprecation process is to communicate at runtime with users if they happen to use such deprecated feature. 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.

e.g. “X-DEPRECATION-NOTICE” : “The usage of lower-cased search on variants.price.currencyCode is deprecated”

Update action limit

For performance reasons, the maximum number of update actions within a single request is limited to 500.

Searchable value size limit

For performance reasons the maximum size of a searchable field within an AttributeDefinition can not exceed 10922 characters.