USI Registry System
Policy and Procedure for Web Service Versioning
The USI Registry System provides a Web Service, containing multiple methods, allowing authorised training bodies to initiate direct, system-to-system interactions with the Registry System.
Over time, the features of the web service and, as a result, the interface specifications are expected to change.
This brief document describes the policy and procedure for versioning of the USI Registry System Web Service.
The intended readers of this document are:
- The USI Registry System Development team
- The USI Registry System Operations team
- Developers of systems (usually Student Management Systems) that consume the USI Registry System Web Service
Web Service Versioning Policy
Web Service Versioning for the USI Registry System comprises two parts – Minor versions and Major versions.
The version identifier of the Web Service and its specification is denoted as MM.NN, where MM denotes the major version number and NN denotes the minor version within that major version. For example, the first Minor Version of Major Version 2 would be denoted as version 2.1. Note that leading zeroes (in both parts) are suppressed.
The version identifier is included in the WSDL as a Documentation element, as shown in the example below:
As a general rule, all changes to the USI Registry System web service interface specification shall be “non-breaking”. That is, the changes shall be implemented such that consumers of the service can continue to use existing features without changing their interface. These changes shall result in a Minor Version of the specification. 7 December 2016 Page 2 of 2
As there are expected to be a large number of consumers of the web service, perhaps hundreds of installations or more, the decision to implement a Major Version must be taken with serious consideration of the impact on the user community.
The release of a new Major Version will result in the creation of a new end-point for the service, reflecting the Major Version. The previous and new end-points will co-exist for a period of time – see Version Support below.
In addition, a Major Version shall not be retired within 12 months of it being replaced in production by a new Major Version. That is, consumers will have a minimum of 1 year to migrate to a new Major Version, in the (exceptional) case that more than 1 Major Version is made available in a 12 month period.