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.
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:
- No values or fields will be changed or deleted in the same API Version
- Every change within the same API version does only include additional information
- new fields and values within an existing object
- new messages for the Messages API
- new API endpoints
- required fields becoming optional
For more information, see this blog post.
Last update: 27/01/2017
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.
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.