SOA Policy Service Versioning Standards

Size: px

Start display at page:

Download "SOA Policy Service Versioning Standards"

Scott Long
5 years ago
Views:

1 SOA Policy Service Versioning Standards

2 Contents Document Location... 3 Document Revision History... 3 Related Policies... 3 Terminology Used in this Document... 4 Definitions Purpose Scope Concepts Service Compatibility Service Change Types Versioning Strategies Versioning Guidelines Versioned Artifacts WSDL Versioning Deployment Units Versioning Net-New Service vs. New Service Version Triggering Major Release Triggering Minor Release Triggering Micro Release References SOA COE 2

3 Document Location TBD Document Revision History Version Date Author Description E.Neroslavskaya Sharon McMillian Edited for style/grammar E.Neroslavskaya Updated rule for portlet dependencies E.Neroslavskaya Updated rule for WSDL versioning to reflect version in port name and in documentation Vladimir Olenin Rearranging the contents, clarifying the points Related Policies Policy SOA Standards - Service Naming Conventions Location TeamSites - SOA Methodology SOA COE 3

4 Terminology Used in this Document This document uses the following terminology: MUST: This word means that the definition is an absolute standard. MUST NOT: This phrase means that the definition is an absolute prohibition. SHOULD: This word means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. SHOULD NOT: This phrase means that there may exist valid reasons in particular circumstances when the particular behaviour is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behaviour described with this label. MAY: This word means that the standard is optional. The service developer may choose to include the item based on the needs of their design. The above definitions are loosely based on the RFC 2119 Key words for use in RFCs to Indicate Requirement Levels as described at: Definitions Term Major Release Minor Release Definition A Major release (i.e. a release which introduces significant changes to the existing functionality or new functionality) will result in the version of the service being increased by 1.0 and Minor/Micro reset to 00. Changes to a service which are disruptive in nature as they break the contract between the service and the clients of the service or changes that require significant effort to implement (i.e. clients must re-certify or rerun conformance testing) Example: Service version 5.00 is not compatible with service version 4.05 The Major version change MUST be shown in Service Specification, Service: WSDL targetnamespace, endpoint, soapaction, deployment unit (Backward compatible) A change to a service which does not require immediate changes to any consuming code, although the service specification has changed in a Backward compatible way. Example: Service version is compatible with Service version SOA COE 4

5 Micro Release From version , a minor change would lead to (bug fixes/implementation changes) A change to the implementation of a service, which should not impact any consumers, since the service continues to conform to the published specification. Example: Service version is bug fixes for service version SOA COE 5

6 1 Purpose The purpose of this document is to define the ehealth Ontario policy regarding a service versioning strategy which is to be followed by the service designers/developers while working on service contracts and maintaining services through the lifecycle. The strategy is based on the creation of stable contracts between ehealth and the consumer community. These contracts will evolve over time, but will always do so through a wellmanaged change process that is capable of supporting older versions and new versions at the same time thus addressing the main challenges: Facilitating the delivery of changes by the provider. Minimizing disruptions to consumers due to changes. 2 Scope The scope of the versioning standards described in this document includes all ehealth Ontario HIAL exposed services and services described in the SOA Service Catalog. While the discussion and examples are focused on Web Services (i.e. services defined with a WSDL and SOAP), the basic versioning principles apply to other approaches such as XML over JMS, REST and BPEL Processes. SOA COE 6

7 3 Concepts Service versioning is a very important feature of the HIAL, allowing multiple versions of the same service to be operational at the same time. Service interfaces are established based on standards and long standing business processes; however, even the most solid standards change over time. By supporting versions of service interfaces, the HIAL enables evolution in the EHR. New systems can be brought on-line to consume new features in the EHR without breaking legacy functionality. Legacy features can be slowly phased out in a predictable, scheduled manner. 3.1 Service Compatibility There are two types of changes; Service Contract changes and Service Implementation changes. These changes lead to following compatibility scenarios: Backwards Compatible changes These are changes made to the contract that will not break previous client versions, for example, adding optional fields or adding a new endpoint. Non-backwards Compatible changes These are changes made to the contract that require changes to previous client versions, for example, removing a mandatory field, removing an existing endpoint or changing the protocol used by the Web Service. Forward Compatible Changes These changes allow newer versions of the service to be deployed without breaking existing clients. The service can accommodate a number of unknown and unexpected features by supporting extensibility through XML Schema wildcards. 3.2 Service Change Types Service Contract changes are changes which require a change to the service interface. These changes are generally not directly backwards compatible. These changes can be either functional or semantic. Functional changes to the functionality provided by the service, such as: Adding new functionality to the service Changing an existing functionality provided by the service Removing existing functionality from the service Semantic changes to the information model used by the service, such as: Adding new data elements to the information model Changing an existing data element from the information model SOA COE 7

8 Removing an existing data element from the information model Binding new data types to the existing information model Binding a new vocabulary to the existing information model, etc. Service Implementation changes are changes which do not trigger a change to the service interface. Such changes maintain backward compatibility. These changes can be: Bug fixes fixing a faulty functionality of the service Performance/Scalability improvements improving nonfunctional aspects of the service Technology stack upgrades changes to the underlying infrastructure upon which the service is implemented 3.3 Versioning Strategies Even though there is no de facto versioning technique for the Web Service contracts, a number of common and advocated versioning approaches have emerged, each with its own benefits and trade-offs. Three known strategies are: Strict (New Change, New Contract) Any compatible or incompatible changes result in a new version of the service contract. This approach does not support Backwards or Forwards compatibility. Flexible (Backwards Compatibility) Any incompatible change results in a new version of the service contract. The contract is designed to support Backwards compatibility but not Forwards compatibility. Loose (Backwards and Forwards Compatibility) Any incompatible change results in a new version of the service contract. The contract is designed to support Backwards compatibility and Forwards compatibility. Each versioning strategy has its pros and cons. They are described in detail in Ref2: Web Service Contract Versioning Fundamentals. The table below summarizes how the three strategies compare based on three fundamental characteristics: Strictness Strictness describes the rigidity of the contract versioning options. The Strict approach clearly is the most rigid in its versioning rules, while the Loose approach provides the broadest range of versioning options due to its reliance on wildcards. Governance Impact This reflects the amount of governance burden imposed by a strategy. Both Strict and Loose approaches increase governance impact but for different reasons. The Strict approach requires the issuance of more new contract versions, which impacts surrounding consumers and infrastructure, while the Loose approach introduces SOA COE 8

9 the concept of unknown message sets that need to be separately accommodated through custom programming. Complexity This reflects the overall complexity of the versioning process. Due to the use of wildcards and unknown message data, the Loose approach has the highest complexity potential, while the straight-forward rules that form the basis of the Strict approach make it the simplest option. Characteristic Strict Flexible Loose Strictness High Medium Low Governance impact High Medium High Complexity Low Medium High SOA COE 9

10 4 Versioning Guidelines 4.1 Versioned Artifacts In a SOA environment these artifacts require versioning: Abstract Service-related Names: Business Service Specification WSDL-related Constructs: the WSDL filename the targetnamespace defined by the WSDL (also in the top-level <definitions> tag). By extension, the target namespace is the logical prefix for the name of each entity defined in the WSDL. the soapaction the schemalocation of each imported XSD file the endpoint location attribute for the address element of each service port Schema-related Names: the XSD filename (if the schema is not embedded in a WSDL) the targetnamespace defined by the schema (either embedded in the WSDL or a stand-alone XSD) The schemalocation of each imported XSD file Deployment Unit: REST: WS-Policy: deployment package (.ear,.war) MANIFEST.MF entries Resource endpoints TBD The sections below provide more detailed information about versioning of some of these artifacts WSDL Versioning Web Service contracts have versioning concerns embedded in them and support the ability to run multiple versions and versioning releases. Following are the summary, for more details refer to SOA Policy Service Naming Conventions. SOA COE 10

11 WSDL construct targetnamespace documentation Schema/wsdl location Version Pattern Policy: 7.2 SOA-NM-WS WSDL Namespace Pattern Policy: 7.3 SOA-NM-WS WSDL Documentation MM </wsdl:documentation> Policy: 7.4 SOA-NM-WS WSDL/XSD File Names r>/<filename> or in the case of a file system: file://ca/ehealthontario/ws/<domain>/<servicename>/v<major>.<min or>/<filename> for Datapower artifacts: local://<domain>/<servicename>/v<major>.<minor>/<schemas>/<filename> Service Port Action (WS-A) Service Endpoint Policy: 7.65SOA-NM-WS WSDL Constructs - Ports SOAP 1.1 port <servicename>soap11port_<vmajor> SOAP 1.2 port <servicename>soap12port_<vmajor> Policy: 7.6 SOA-NM-WS Action Names or> Hl7v3: urn:hl7-org:v3:{interaction ID}.{Interaction Major version} Policy: 7.6 SOA-NM-WS Service Address Endpoints /<domain>/[subdomain]/<servicename>/[v<major>.<minor>] For more details refer to SOA Policy Service Naming Conventions. Sample: <wsdl:definitions xmlns:wsdl=" xmlns:wsa=" xmlns:tns=" targetnamespace=" <wsdl:documentation>lab Reports </wsdl:documentation> <wsdl:porttype name="labreportservice"> <wsdl:operation name="putorder"> <wsdl:input wsa:action=" message="tns:putorderrequest"/> SOA COE 11

12 </wsdl:operation> </wsdl:porttype> <wsdl:binding name="labreportservicesoap11binding" type="tns:labreportservice"> <soap:binding style="document" transport=" <wsdl:operation name="putorder"> <soap:operation soapaction=" <wsdl:input> <soap:body use="literal"/> </wsdl:input> </wsdl:operation> </wsdl:binding> <wsdl:service name="labreportserviceports"> <wsdl:port name="labreportservicesoap11port_v01" binding="tns:labreportservicesoap11binding"> <soap:address location=" </wsdl:port> </wsdl:service> </wsdl:definitions> Deployment Units Versioning Deployment Units Isolation Deployment units for different services SHOULD be packaged and managed separately, providing ability to deploy and manage different service version concurrently and minimizing the impact to consumers. Example: Packaging service components in separate EAR files, portlets in separate WAR files, Mediation in a separate Datapower proxy or WESB module Deployment Unit Filename Deployment unit (EAR, WAR, etc.) filename must include version information, following pattern: <servicename>_v<major>.<minor>.extension Example: ClientManagementService_V01.02.ear SOA COE 12

13 Deployment Unit Manifest The Deployment Unit MUST include an inside file specifying the full version information. For Java-based components, the MANIFEST.MF file MUST include: Implementation-Version: <major>.<minor>.<micro>.<build> Specification-Version: <major>.<minor>.<micro> Example: Specification-Version: Implementation-Version: For.NET services, use the Assembly Manifest, version attribute. The Ant Manifest task may be used to update the MANIFEST file automatically: Assembly versioning: Assembly manifest: The build number MUST be included in the full version information of the service deployment unit in the Manifest file. Release notes for the deployment unit/application component should include all services and their versions. Example: IF release 3.3, build 45 should include notes with all services Portlet Versioning ClientRegistry ProviderRegistry Each portlet should be packaged in a separate WAR file, to minimize the impact of the changes to the consumers and to provide efficient management options. Example: The OLIS portlet release does not affect consumers of the DPV portlet. The WAR filename must include version information, in the following pattern: <portletname>_v<major>.<minor>.war Example: OLISPortlet_V01.02.war Each portlet MUST include a full version information file MANIFEST.MF or version.properties. SOA COE 13

14 The portlet description MUST include the Major version number in the portletid and make it visible to consumers: WSRP Protocol: 01.html#_PortletDescription portletid: A portlet assigned identifier which is invariant across deployments of compatible versions of the portlet. All dependent portlets MUST be listed in MANIFEST.MF or version.properties file. Depends-On: Portlet<major>.<minor>; Portlet<major>.<minor> This would minimize the management effort to keep track of dependencies. Example: For OLIS Portlet 3.0 which is dependent on Client Selector Portlet 3.2 and Digital Imaging Portlet 1.0, OLIS Portlet war file would include MANIFEST.MF entry: Depends-On: ClientSelector_V03.02.war;DIPortlet_V01.war 4.2 Net-New Service vs. New Service Version Evolutionary changes must result in a New Service Version: - shows a clear heritage to prior service specifications, reflecting the same charter. - essentially the same, although evolved, business or technical characteristics Revolutionary changes must result in a New Service: - new charter - changes in the semantic characteristics, that is, the business task The provider must determine whether a change is evolutionary or revolutionary based on impact to consumers and to the provider. 4.3 Triggering Major Release Any backward incompatible change will result in a new major release of the service. Table below provides guidance on what change is considered to be backwards in compatible. Area of Change Backward Compatible Non-backward Compatible Interface Changes Add operation Remove operation Add new optional data structures to the input Change data type of input/output parameter SOA COE 14

15 Area of Change Backward Compatible Non-backward Compatible Relax schema (e.g. making fields optional, change to less restricted type) Add new interface, binding Add extra data structures in the output Change order of parameters Binding protocol changes (SOAP, JMS) Policy Changes Change in QoS WS-Policy changes like in security, WS-RM Change in agreed Domain values in the output Implementation Changes Simple bug fixes SLA change Internal behaviour changes (e.g. Logging added) Affecting interface change Functionality Changes n/a New functionality represents existing interface. 4.4 Triggering Minor Release Various changes are possible, without impacting existing consumers. For example: New operations are added. An operation signature remains the same, but its behaviour or a quality changes to comply with the changed specification; although the consuming application still works, the consumer may still want to consider whether the change in behaviour or quality is acceptable and what impact it has. An operation signature is changed but it can still be used without a change in the consuming software, for example, some optional input parameters have been added. 4.5 Triggering Micro Release The new implementation might have been re-factored, or run on an upgraded release of middleware or operating system, all without impacting the service functionality or its quality in an adverse way. Service quality (e.g. availability, reliability) may be strengthened, but should not be weakened unless agreed in advance with service consumers. SOA COE 15

16 Implementation-replacement releases of a service do not require new version numbers within the service name, but the service deployment unit (implementation modules) will change, and these must be subject to usual configuration management/version management disciplines. SOA COE 16

17 5 References ID Reference Location/Description Ref1 Ref2 Ref3 Ref4 Web Service Contract Versioning Fundamentals Part I: Versioning and Compatibility Web Service Contract Versioning Fundamentals Part II SOA Contract versioning The Service Versioning Balancing Act vice_versioning_balancing_act.pdf SOA COE 17

WSDL. Stop a while to read about me!

WSDL. Stop a while to read about me! WSDL Stop a while to read about me! Part of the code shown in the following slides is taken from the book Java by D.A. Chappell and T. Jawell, O Reilly, ISBN 0-596-00269-6 What is WSDL? Description Language