Date post: | 28-Jan-2015 |
Category: |
Technology |
Upload: | kjell-sverre-jerijaervi |
View: | 105 times |
Download: | 0 times |
Service Oriented ArchitectureContract Versioning
Kjell-Sverre JerijærviMicrosoft Services
December 2008
SOA Design Maturity
0: Just a Bunch of Web-Services
1: Design Policies for Contracts
2: Service Models and Data Models
3: Governed Services & Contracts
4: Closed-Loop SOA Governance
SOA Principles
Standardized Service Contracts
Service Loose Coupling
Service Abstraction
Service Reusability
Service Autonomy
Service Statelessness
Service Discoverability
Service Composability
Σ Service-Orientation & Interoperability
http://www.soaprinciples.com/
Versionable Artifacts
Contracts: Service, Messages, Data
WSDL: Service Interface + Messages + Policies
XSD: Data contracts as XML schemas
Deployment
Interface v2.0
Implementation v2.0
Deployment
Interface v1.0
Implementation v1.1
Implementation v1.0
SchemaSchema
Operation
Operation
Policy
Policy
Policy
Endpoint
Endpoint
© JJDubray
Why Contract Versioning
Without formal contract versioning guidelines, bad effects are likely:
Too many versions of the same service running in production
Maintaining mapping between consumers and many service versions is troublesome
Consumers will not know which version to use if too many versions are available
New business rules will not be used by old consumers if old versions do not get deprecated
Versioning Guidelines
Define standards
Service version conventions
Rules for WSDL design
Rules for XSD design
Version conventions for WSDL/schema namespaces
Version conventions for WSDL/schema artifact names
Define policies & governance
Number of service versions supported
How to identify a service and its version
How each version of the service is represented in the service registry
Processes for service lifecycle management and how a service is represented in the repository
The Ripple Effect
Standardized Service Contracts
Composite Services
Services
Aggregate Schemas
Consumers
Schemas
Flow & Decisions
Service Logic (code)
Versioning OverviewArtifact Change Major Minor Point
Service Breaking X
Service Non-Breaking X
Composite Service Incompatible Service X
Composite Service Compatible Service X
Service Incompatible Schema X
Service Compatible Schema X
Schema Breaking X
Schema Non-breaking X
Schema Aggregate Incompatible Schema X
Schema Aggregate Compatible Schema X
Code Bug fix / maintenance X
Code Safe modifications X
Code Semantic / Unsafe modifications X
Other service artifacts Any modification X
SCHEMASMessages & Data Types
Schema Versioning
Schema design guidelines
Use backwards compatible schemas
Support forwards compatible schemas (extensibility)
Elective: consumer variations (extensions)
Schemas should be designed for extensibility, not to avoid versioning (wildcards)
Compatibility MUST be defined by a versioning scheme
Major (breaking change): incompatible
Minor (non-breaking change): compatible
Compatibility can be either backwards or forwards or both
Schema Compatibility Recommendation
It is recommended to have a simple and explicit schema versioning policy
Use a “Flexible/Strict” compatibility strategy
Flexible: Safe changes to schemas are backwards compatible and cause just a point version
Strict: All unsafe schema changes must cause a new schema version and thus a new service version
Do not require forwards compatible schemas (Loose, wildcard extensibility)
Avoid implementing some smart automagical mechanism for handling schema version issues in the service logic
Rather use backwards compatibility, explicit schema versions and support multiple active service versions
Compatibility Overview
Strategy Change Major Minor Point FW
Strict Breaking X
Strict Non-Breaking X
Flexible Breaking X
Flexible Non-Breaking X
Loose Breaking X X
Loose Non-Breaking X X
Flexible/Strict Breaking X +
Flexible/Strict Non-Breaking, Safe X +
Flexible/Strict Non-Breaking, Unsafe X +
Versioning F/S RevisitedArtifact Change Major Minor Point
Service Breaking X
Service Non-Breaking U S
Composite Service Incompatible Service X
Composite Service Compatible Service U S
Service Incompatible Schema X
Service Compatible Schema U S
Schema Breaking X
Schema Non-breaking U S
Schema Aggregate Incompatible Schema X
Schema Aggregate Compatible Schema U S
Code Bug fix / maintenance X
Code Safe modifications X
Code Semantic / Unsafe modifications X
Other service artifacts Any modification X
Schema Versioning Rules
The Schema version MUST be independent of the Service Version itself, however, an increment in schema version MUST result in an increment of the Service version
An increment of the version of a type included or imported in a schema MUST result in a version increment of this schema
A Major increment of the schema version of an operation message type MUST result in a major increment of the service version
A message consumer receiving message of an incompatible version MUST generate an exception, even if the message could be understood and processes by removing any portion that was not recognized
Schema Version Tracking
Schemas MUST include mandatory major version in the XML namespace
XML Namespace values MUST be constant for a given schema type and a given major version
Message type schemas should include minor and point version custom attributes on the message type root element of type xsd:int
Whether XML validation is used or not, each message consumer MUST verify that the major version is compatible with its implementation (through XML namespace)
Minor and Point versions MUST NOT affect namespace
Naming Conventions I
Namespaces and artifact names used by schemas will be versioned by the industry standard YYYY/MM format for namespaces:
urn://schemas.microsoft.com/customer/2006/01/
Likewise the YYYY-MM format for files:http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
Compatible with…
Compatibility is “not” between consumers and providers
Consumers must be compatible with the Standardized Service Contracts
Providers must be compatible with the Standardized Service Contracts
…this also facilitates principle #2:
Service Loose Coupling
Schema Compatibility
SENDER: v1.0 XSD
1..n Elements
Wildcard
RECEIVER: v1.1 XSD
1..n Elements
Wildcard
1..n Elements (optional)
Wildcard
v1.0 XML
RECEIVER: v1.0 XSD
1..n Elements
Wildcard
SENDER: v1.1 XSD
1..n Elements
Wildcard
1..n Elements (optional)
Wildcard
v1.1 XML
Backwards Compatible Schema
Forwards Compatible Schema
Service Backwards Compatibility
Consumer v1.0
v1.0 REQUEST XSD
1..n Elements
Wildcard
v1.0 RESPONSE XSD
1..n Elements
Wildcard
Provider v1.1
v1.1 REQUEST XSD
1..n Elements
Wildcard
1..n Elements (optional)
Wildcard
v1.1 RESPONSE XSD
1..n Elements
Wildcard
1..n Elements (optional)
Wildcard
v1.0 XML
v1.1 XML
Backwards Providers
Providers that handle old request message schemaversions received are backwards compatible services
Consumers are responsible for handling old responsemessage schema versions sent by providers
The service provider implementation MUST keep track of the schemas for all the minor versions for incoming messages and validate each incoming message based on its minor version number for a given major version
Schema duck-typing can be used to deduce version
Service Virtualization and intelligent routing is an alternative mechanism for backwards compatibility
Service Forwards Compatibility
Consumer v1.1
v1.0 REQUEST XSD
1..n Elements
Wildcard
v1.0 RESPONSE XSD
1..n Elements
Wildcard
Provider v1.0
v1.1 REQUEST XSD
1..n Elements
Wildcard
1..n Elements (optional)
Wildcard
v1.1 RESPONSE XSD
1..n Elements
Wildcard
1..n Elements (optional)
Wildcard
v1.1 XML
v1.0 XML
Forwards Consumers
Consumers that handle upgraded response messageschema versions are forwards compatible consumers
Providers are responsible for handling upgraded requestmessage schema versions sent by consumers
Extensibility design guidelines enable existing consumers to continue operate unchanged even when the service provider is upgraded in a forwards compatible way
If the consumer validates the incoming messages sent by the provider, they will pass validation (because of the extensibility rules defined)
Breaking changes is conveyed using a new major version and thus a new XML namespace
Schema Wildcards
Loose compatibility through schema wildcards
Both request messages and response messages can be forwards compatible
Might lead to fuzzy contracts with unclear semantics and poor discoverability
Implemented using XSD Extensibility
<xs:any namespace=”##targetNamespace” processContents=”lax” minOccurs=0 maxOccurs=”unbounded” />
<xs:any namespace=”##other” processContents=”lax” minOccurs=0 maxOccurs=”unbounded” />
Extensions are differentfrom Versions
Extensions are common when consumer specific variations are needed
i.e. specialized relationships between consumers and providers (independently of other consumers)
Extensions MUST be implemented within a single element under the root element of the message type
Recommended element name is <ConsumerArea>
They MUST be separate from the general versioning patterns
Extensions NEED NOT be processed by other message consumers
Extensions MAY belong to any namespace
SCHEMA MODELSFederated, Composable Information Models
Schema Models
EAI CDM: Common Data Model
SOA CIM: Common Information ModelMDMrealm
Resource Type 1 Resource Type 2 Resource Type n
BPM: HumanTask + Workflow
Business Process Integration (domain CRM)
Task:Message
Contract A
Event:Message
Contract B
Business Process Integration (domain OHS)
Task:Message
Contract K
Event:Message
Contract L
BPI domain information model: business event messages as projections of CIM data entitites
Federated models: required for B2x integration, cannot enforce model on the outside world
Enterprise canonical CIM model: might be feasible, but federated models are recommended
Resource Domain Model Federated CIM
Model Mismatch:ER vs XML Schema
?????
Customer Order
1
0..n
PO
Customer
name
address
Shipment
Shipment0..n
0..n
POs
Customer
name
address
PO# POs
Customer
name
address
PO#
Shipment
name
address
PO#
PO#
DSL-Driven Models
EnterpriseData
ModelDSL
Message TypeDSL
EnterpriseData
Model
Message TypeMessage
TypeMessage
TypeDefinition
references references
Message TypeMessage
TypeWSDL
Message Type
Message TypeMessage
TypeMessage
TypeXML
Schema
Based on
Based on
referencesGenerate
SERVICE INTERFACESCapabilities / Operations
Service Versioning
Must allow for multiple generations of versioning of service design artifacts and runtime endpoints
Must support multiple versions for Service Requests at runtime for the same endpoint
Must allow for multiple branch versioning
Must support the following use casesCreate a new service version
Change message type schema
Change service interface
Change service bindings
Change service non machine readable metadata
Consume a new service version
Create a new consumer version
Decommission a service version
Service Contract Design
Define service version convention into three categories:
Major version change (breaking change)Dropping deprecated operations
Change an operation signature in a manner that could break consumer compatibility
Change service input and output message type
Service has gone through a major rewrite
Minor version change (non-breaking change)Change of the service contract (schema, interface, etc) but maintain the compatibility of the existing consumers
Consumers may still consider whether the change of the service contract is acceptable
Point version change (build number)Change of service implementation but maintaining the service contract the same
Naming Conventions II
Namespaces and artifact names used by WSDL must follow same conventions as for schemas
Major, minor, point are appended in the service nameCONTOSO_3_1_120 for v3.1.120
Consumer can connect to a particular ACTIVE version of a service by using the WS-Addressing “To” element
soap://contoso/services/customer_3
soap://contoso/services/customer_3_pre
No separate version elements are needed in the SOAP header
Versions: Active, Published, Discovery
v1.0 (decommissioned)
v1.1 (deprecated)
v2.1 (deprecated)
V3.0 (deprecated, pre)
v3.1 (latest major)
time
active
published
v2.0 (decommissioned)
discoverable
Active Service Versions
There should not be more than 3 major versions of the same service running in the production environment
Maintain immediate predecessor minor/point version of the latest major version of the service
If new major service version is introduced and there are already 3 versions of service running, the oldest version of the service must be decommissioned
N Latest (Major) version (Published)
N- Immediate Predecessor (minor/point) version of the Latest Major (Deprecated)
N – 1 Deprecated
N – 2 Deprecated
N – 3 Decommissioned
Once the next major version is released (N+1), the immediate predecessor of N, (aka N-) must be decommissioned
Use a SOA governance process to enforce that the consumers upgrade to the newer “Active” versions to maintain the support from the service Provider
Service Registry
Potential consumers will always be directed to the published (latest major) version of a service in the registry, they cannot search for minor or point versions
Potential consumers can only search for the 3 last major version of a service
This approach eliminates the need for managing too many versions
There is no need to alter the manner in which green page queries are performed in the UDDI model
Use a repository to maintain and document the relationship among multiple versions of the same service in a meaningful manner
Registry (or registar role) will be responsible for notifying consumers of new published versions
Other Service Artifacts
These recommendations do not attempt to model extended service metadata
Attachments
Annotations
Other non-machine readable metadata
Changes to service artifact versions MUST be indicated as at least as point versions (since the implementation should change at a minimum)
When this type of metadata changes, there are enough mechanisms in this guideline to convey and detect
Incompatible version
Compatible versions
…even when the contract did not change
SERVICE MODELSUtility, Entity, Activity, Process, Task, Workflow
Composite Services / Service Bus
Process - Resource LifeCycle
Activity
Entity Entity
Capability
LOB Systems
Servic
es
Orch
estr
ati
on
s
CommonInformation
Model(Resources)
Business Process
InformationModels
(Documents)
Wo
rkfl
ow
Human Task -Episodic Process
Human Task -Episodic Process
I&
AM
: C
laim
s-
Au
thZ
BizEvents
BizProcess
MDMrealm
Service Ontology
DESIGN GUIDELINESServices, Messages, Data Types
Service & Messages Design
Web-Services Interoperability best practices:WS-I BasicProfile 1.xwww.ws-i.org
Recommended WSDL style:Document/Literal Wrapped (D/LW)
One message in – One message out
Use Message Exchange Patterns
Data contracts wrapped in Messages
One Way, Request-Response, Notify
Document/Literal Wrapped WSDL
These are the basic characteristics of the document/literal wrapped pattern:
The input and output message has a single part
The part is an element
The element's complex type has no attributes
The input element has the same name as the operation
StrengthsThere is no type encoding info
Everything that appears in the soap:body is defined by the schema, so you can easily validate this message
You have the method name in the SOAP message
Document/literal is WS-I compliant, and the wrapped pattern meets the WS-I restriction that the SOAP message's soap:body has only one child
WeaknessesThe WSDL is complicated
Look ma, no attributes
Data Type Design
Prefer Venetian Blind pattern over Salami Slice pattern
DO NOT use anonymous types in XML schemas(unqualified Russian Doll pattern)
Use wrapped arrays/collections
Elective: allow extensibility after element and attribute definitions
New forward compatible versions of a schema MUST be extended within the target namespace of the original schema
Extensibility to other namespaces MUST be disallowed in places other than the reserved extensibility point
XSD Best Practices
XML schema design alternatives for this instancedocument:
<Book>
<Title>Illusions</Title>
<Author>Richard Bach</Author>
</Book>
Russian Doll
<xsd:element name="Book">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Title" type="xsd:string"/>
<xsd:element name="Author" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</element>
Salami Slice
<xsd:element name="Title" type="xsd:string"/>
<xsd:element name="Author" type="xsd:string"/>
<xsd:element name="Book">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="Title"/>
<xsd:element ref="Author"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Global Element Declaration,@substitutionGroup
Namespace exposure: always ”qualified”
Venetian Blind
<xsd:simpleType name="Title"><xsd:restriction base="xsd:string” />
</xsd:simpleType>
<xsd:simpleType name="Name"> <xsd:restriction base="xsd:string” />
</xsd:simpleType>
<xsd:complexType name="Publication"> <xsd:sequence>
<xsd:element name="Title" type="Title"/>
<xsd:element name="Author" type="Name"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="Book" type="Publication"/>
Namespace exposure toggling: ”qualified” or ”unqualified”
WCF Contract Design
Prefer using the WCF DataContractSerializer (DCS) over theXmlSerializer
DCS prefers Venetian Blind, supports Salami Slice
Document/Literal Wrapped WSDL is required by DCS
Follow message part naming conventions defined by Microsoft
DCS supports only elements for data, not attributes
Not supported: <amount currency=”NOK”>123</…>
Wrapped arrays/collections are preferred by DCS
DCS: elementFormDefault must be ”qualified”
DCS: element substition not supported (@substitutionGroup)
Wrapped Arrays
<xs:complexType name="ItemType”><xs:sequence>
<xs:element name="Id" type="xs:long" />
<xs:element name="Value” type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ItemListType"><xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="Item" type="tns:ItemType"/>
</xs:sequence>
</xs:complexType>
<xs:element name="ItemList" type="tns:ItemListType" />
WSDL Operation Message
<wsdl:message name="GetItemRequest”>
<wsdl:part element="tns:GetItemRequestType" name="parameters” />
</wsdl:message>
<wsdl:message name="GetItemResponse”>
<wsdl:part element="tns:GetItemResponseType” name="parameters” />
</wsdl:message>
<wsdl:portType name="InspectValues”>
<wsdl:operation name="GetItem”>
<wsdl:input message="tns:GetItemRequest" name="GetItemRequest"></wsdl:input>
<wsdl:output message="tns:GetItemResponse" name="GetItemResponse"></wsdl:output>
</wsdl:operation>
</wsdl:portType>
WSDL Fault Message
<wsdl:message name="GetCustomerRequest">
<wsdl:part element="tns:GetCustomerRequest" name="parameters" />
</wsdl:message>
<wsdl:message name="GetCustomerResponse">
<wsdl:part element="tns:GetCustomerResponse" name="parameters" />
</wsdl:message>
<wsdl:message name="FaultDetailList">
<wsdl:part element="fault:FaultDetailList" name="detail" />
</wsdl:message>
<wsdl:portType name="CustomerService">
<wsdl:operation name="GetCustomer">
<wsdl:input … />
<wsdl:output … />
<wsdl:fault message="tns:FaultDetailList" name="FaultDetailList" />
</wsdl:operation>
</wsdl:portType>
INTEROPERABILITYDiversity & Composability
Platform Diversity
JAVA
.NET
Schema Interop Issues
Consumers might not support normalized/modular WSDL+XSD, but require a single/flat WSDL file
Most legacy ASMX consumers
Most Java tools (e.g. Eclipse)
Most AJAX toolkits
Rich Internet Application (RIA) platforms (e.g. Flex/Flash)
Some Web2.0 mashup tools
XSD data types might not be supported by platform.NET has no support for e.g. xs:date, xs:positiveInteger
Unsupported data types typically become string objects
Some xs:nillable elements might not be supported by platform
Some elements might be required to be xs:nillable by platform
Use of attributes for data
Use of attributes to annotate data elements
Service Interop Issues
Support level for WS* standards varies wildly between platforms
SOAP 1.1 or SOAP 1.2WS* support in WCF defaults to Soap12Addressing10
Most legacy platforms support only Soap11
Typical WS-Security interop issues:Which version of the standard the platforms support
Token type for authentication
Message or transport security
Order and level of encryption and signing
Establishment of secure conversations
Some platforms do not support WS-Policy/WS-SecurityPolicyNo policy metadata in WSDL, e.g. when using Java Spring-WS
All policy metadata must be communicated out-of-band
Web Service Contract Design and Versioning for SOA
Thomas Erl, David Orchard et.al. (826 pages)http://www.soabooks.com/wsc/default.asp
Credits
John Evdemonhttp://msdn.microsoft.com/en-us/library/ms954726.aspx
Jean-Jacques Dubrayhttp://ebpml.org/com/an_introduction_to_soa4.swf
David Orchardhttp://www.xml.com/pub/a/2004/10/27/extend.htmlhttp://www.w3.org/TR/xmlschema-guide2versioning/
Don Smith http://blogs.msdn.com/donsmith
Roger L. Costello & cohttp://www.xfront.com/GlobalVersusLocal.html
Russel Butekhttp://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/
References
Principles of Service Design: Service Versioninghttp://msdn.microsoft.com/en-us/library/ms954726.aspx
Using Message Contractshttp://msdn.microsoft.com/en-us/library/ms730255.aspx
Practical WCF DataContract Ruleshttp://kjellsj.blogspot.com/2008/03/wcf-datacontractserializer-schema-rules.html
WCF DataContract Ruleshttp://msdn2.microsoft.com/en-us/library/ms733112.aspx
Which WSDL stylehttp://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/
QUESTIONS?
© 2008 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other
countries.
The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to
changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of
this presentation.
MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.