Core Service versioning

To support backward compatibility, new releases of SDL Web (formerly called SDL Tridion) return data that an old client can handle gracefully. For Java, the XmlBeans proxy generator is most reliable to handle compatibility issues.

Every SDL Web release aims to expose Core Service endpoints that are backward compatible with existing Core Service clients (the service contract is maintained). This means that typically, if you upgrade to a new release of SDL Web, you can leave your code that interacts with the Core Service unchanged. Your existing calls to the Core Service interface continue to work, because the existing service contract is still supported.

Of course, if you want to make use of new functionality offered by a new release (new parameters, new methods, and so on), you must modify and recompile your existing code, and explicitly connect to the new end points.

Service contract version numberSupports endpoints introduced inIntroduced in
2011SDL Tridion 2011, SDL Tridion 2011 SP1SDL Tridion 2011 SP1
2012SDL Tridion 2011 SP1, SDL Tridion 2013SDL Tridion 2013
2013SDL Tridion 2011 SP1, SDL Tridion 2013, SDL Tridion 2013 SP1SDL Tridion 2013 SP1
201501SDL Tridion 2011 SP1, SDL Tridion 2013, SDL Tridion 2013 SP1, SDL Web 8SDL Web 8
201603SDL Tridion 2011 SP1, SDL Tridion 2013 SP1, SDL Web 8, SDL Web 8.5SDL Web 8.5

In addition, what a Core Service call returns (the data contract) is not versioned and will change over time. As a result, a new release of SDL Web may change the data returned by a Core Service call. For example, the same command may result in data being returned that is of a data type that did not exist in a previous release.

You can guard against this by checking for specific types of data being returned that indicate a compatibility issue. If you detect such data being returned, you can then choose how to handle the unsupported return data.

Specifically, this means the following:

  • Existing properties will have the same type in the new release.
  • New properties will be optional and only affect an old interface call if the client cannot handle the new property. Deserialization of such unexpected data may fail on some Web service proxies (though not on the recommended proxies: WCF and Java Axis XmlBeans).
  • New enumeration (enum) values will be returned to an old interface call as a reserved enum value called UnknownByClient.
  • New subclasses will be downgraded to the nearest base class that exists in the release to which your interface call belongs.

In addition to the service contract and data contract, when calling the Core Service from Java, compatibility also depends on your choice of proxy generator. SDL recommends using Java XmlBeans to generate your proxy.