Version Handling
You need to keep the following points in mind related to the Cloud Connect web service version:
>Each resource will have a version, for example, 1.0.
>The version is part of the Accept header.
>For the unsupported version requests, the response HTTP error 406 NOT ACCEPTABLE is given followed by the supported version list.
Breaking Changes
Generally, SCL Add-on web services are backward-compatible. However, there are some cases where the resource version used by web services is not changed and hence may require you to do some source code changes to keep the application running. The following is a list of such changes that an integrator needs to take care of:
>Adding new endpoints
>Adding new response parameters
>Support of new format by the Content-Type header
>Support of new languages by Content-Language
>Change in the character case. Note that both the web service producer and consumer need to handle the varied casing, making the case changes irrelevant.
NOTE
>The above list is not all inclusive, as additional changes may be added later to the list as and when observed.
>You must use the Tolerant Reader pattern, which is an industry standard. Web service clients must only extract what is needed, ignore unknown content, and expect variation in the response parameters as REST APIs evolve. This ensures backward-compatibility.
Non-Breaking Changes
The following are examples of some backward-compatible changes that are automatically taken care of with the resource version change:
>Always result in a change to the major version number for an API and previous versions will exist for some time to provide software vendor's time-window to switch to new API version. It is recommended to switch to new API versions.
>Renaming a property, whether in header or in request body, such as x-sfnt-vendor to x-sfnt-vendorID
>Removal of property
>Changing the property data type (numeric to string, Boolean to bit/numeric, string to date time, and so on)
>Changing an optional parameter to mandatory
NOTE In our Cloud Connected web services, for a POST/PUT/PATCH request having no body (for example, Register WS), customer's client app needs to set Content-Length header to 0.