Documentation Center

Versions of microservices (Content Interaction Services)

By default, any code you write that interacts with the Content Delivery microservices, also called Content Interaction Services (CIS), is assumed to work with any version of the microservices. But both in Java and in .NET, you can use annotations to specify exactly which version(s) of the CIS your code will work with.

You can find out the CIS version by making a metadata request to the Content Service. The response contains a response header called X-SDL-CIS-Version which lists the version of this CIS.

You can specify that your piece of code:
  • only works from a certain CIS version onward
  • only works up to a certain CIS version
  • works from one CIS version up to and including another, later CIS version
If the CIS does not have a correct version, one of the following things happens:
Java

The Content Service returns a message: Unsupported version: VERSION, where VERSION is the version of the CIS.

.NET
By default, the compatibility check is in "relaxed" mode and as a result, a call throws a NotSupportedException if the CIS version is not a version listed in the annotation. However, in the appSettings section of your Web.config file, you can further configure the result by changing the compatiblity check value:
<add key="service-version-compatibility-check" value="strict" />

If you add this to the appSettings, the call additionally throws a NotSupportedException if the client (Content Interaction Library or CIL) version is higher than the CIS version, even if the method is not annotated.

<add key="service-version-compatibility-check" value="none" />

If you add this to the appSettings, the call ignores all annotations and simply assumes that the CIS version on the receiving end is compatible.

Here are Java code samples demonstrating the use of annotations:
public void example1() {
  /* perform some call on the CIS – should be backwards compatible with 8.1.0 CIS and work with all future versions */
}

@SupportedCisVersion(from = "8.1.1.0", to = "8.1.1.0")
public void example2() {
  /* perform some call on the CIS – will only work if CIS version is 8.1.1.0  
     and will throw ODataClientRuntimeException if CIS version not compatible */
}

@SupportedCisVersion(from = "8.1.0", to = "8.5.0")
public void example3() {
  /* perform some call on the CIS – will only work if CIS version is from 8.1.0 to 8.5.0 inclusive 
     and will throw ODataClientRuntimeException if CIS version not compatible */
}
Here are .NET code samples demonstrating the use of annotations:
// This method will run against any CIS service running.
public void ApiMethod1()
{
  // perform CIS request here
}
  
// this method will only run against versions of CIS of 8.1.1.0 or higher
[SupportedCisVersion("8.1.1.0")]
public void ApiMethod2()
{  
  // perform CIS request here
}
  
// this method will only run against versions of CIS between 8.2.0.0 and 8.3.0.0 inclusive
[SupportedCisVersion("8.2.0.0", "8.3.0.0")]
public void ApiMethod3()
{  
  // perform CIS request here
}