This is the presentation I gave at the 5th International SOA and Cloud Symposium in London, September 2012. If you want moving pictures with it, see the recording at InfoQ: http://www.infoq.com/presentations/Service-Versioning

1. SERVICE VERSIONING
25/09/2012
Service Technology Symposium
London
Ignaz Wanders, Archimiddle
The Balance Between Service Governance and Service
Technology

2. AGENDA
 The Problem of Change
 Compatibility
 Principles
 Service Versioning
 Design Patterns
 Strategies
 Service Version Compatibility
 Forward and Backward Compatibility
 Grammar-based versus Rule-based
 Governing Service Versions
 Design Time versus Run Time
 Technology versus Governance
 Practical Case
 From Big Bang to Mediation
 The Case for Standards
 Conclusion

3. THE PROBLEM OF CHANGE
Archimiddle

4. A SERVICE LANDSCAPE
9/5/2013SERVICE VERSIONING 4
Service X
Client1
Service Y
Service Z
Client 2
Client 3
Client n
What is the impact of a new
version of service X? And of
service Z?

5. 1: COMPATIBLE CHANGE
9/5/2013SERVICE VERSIONING 5
Service X
Client 1
Service Z
Client 2
Client 3 A compatible change allows
service clients to use the
new version transparently
Service Z
v2
New
compatible
version

6. 2: INCOMPATIBLE CHANGE
9/5/2013SERVICE VERSIONING 6
Service X
Client 1
Service Z
Client 2
Client 3
An incompatible change forces
service clients to change as well
in order to use the new version
Service Z
v2
New
incompatible
version
Service X
v2

7. GRADUAL CHANGE
9/5/2013SERVICE VERSIONING 7
Service X
Client 1
Service Z
Client 2
Client 3
A gradual change of clients from
version 1 to version 2, means all
affected services must offer two
versions simultaneously.
Service Z
v2
New
incompatible
version
Service X
v2

8. GENERAL VERSIONING PRINCIPLES
 Clients should not be forced to use the new version immediately
 Gradual client migration
 Retire services gracefully
 Support multiple service versions concurrently
 Limit the number of concurrent versions through governance
 Only the latest version is discoverable
9/5/2013SERVICE VERSIONING 8
time
Old version
New version
Transition period for client upgrade

9. SERVICE VERSIONING
Archimiddle

10. DESIGN PATTERNS
 Canonical Versioning
 Standardized versioning within the service inventory
 Concurrent Contracts
 One service can have multiple contracts, targeted to
 Different clients
 Different usage
 Compatible Change
 Avoid breaking changes
 Version Identification
 Version numbers: major, minor, point release: xx.yy.zzz
9/5/2013SERVICE VERSIONING 10

11. VERSION NUMBERS
 Major release
 Change which is not backward compatible
 Functional change
 Minor release
 Change which is backward compatible
 New capability
 New optional service request parameters
 Point release
 Bug fix
 Performance enhancement
9/5/2013SERVICE VERSIONING 11
xx.yy.zzz

12. STRATEGIES
 In practice, most service changes are incompatible changes!
 So the strategy is less important; you get a new major version anyway
9/5/2013SERVICE VERSIONING 12
Strategy New major New minor New point
Strict Incompatible
change
Compatible
change
Flexible Incompatible
change
Compatible
change
Loose Incompatible
change

13. SERVICE VERSION
COMPATIBILITY
Archimiddle

14. FORWARD & BACKWARD
COMPATIBILITY
 Forward compatibility:
 Today’s version is compatible with future versions
 Existing clients are not impacted by the new version
 Backward compatibility:
 The new version is compatible with today’s version
 Existing clients can start using the new version as if it was identical to today’s version
 In a service landscape, compatibility covers all aspects of the service
interface and contract
9/5/2013SERVICE VERSIONING 14
Including functional aspects!

15. GRAMMAR-BASED VERSUS RULE-
BASED
 Compatibility contracts can be achieved either way:
 Grammar-based compatibility
 Defines exactly how the service communication protocol must be followed by both service
provider and client
 All service clients have the same compatibility contract
 Example: WSDL and XML Schema
 Rule-base compatibility
 Defines which parts of the services communication must be followed by both service provider
and client
 Each service client can have a different compatibility contract
 Example: Schematron
9/5/2013SERVICE VERSIONING 15

16. GOVERNING SERVICE
VERSIONS
Archimiddle

17. DESIGN TIME VERSUS RUN TIME
Design-time versioning Run-time versioning
9/5/2013SERVICE VERSIONING 17
 Define a fixed version value in
the technical service contract
 Example:
 a version identifier in the XML
namespace
 What you see is what you get:
simple governance
 New version requires a new
client build and new client
deployment
 Version value is defined in the
non-technical service contract
 Example:
 a version XML element whose value
is not fixed
 Must be governed
 New version not necessarily
requires a new client build or
deployment

18. TECHNOLOGY VERSUS GOVERNANCE
Technology Governance
9/5/2013SERVICE VERSIONING 18
 WSDL & XML schema
 Very popular
 Well understood
 Imposes versioning strategy
 Strict, flexible, loose
 Great tool support
 Standards-based
 Organizational processes
 Less well understood
 Service-level agreements
 Must define versioning strategy in
soft document
 Tool support?
 No standards
 Proprietary service repository

19. COMMON REAL-LIFE SCENARIO
 Endpoint URL contains version number
 Grammar-based service contract (WSDL & XML schema)
 Version number in XML namespace
 Only a single service version in operation at any one time
 (Hard to have multiple versions using single database, e.g.)
9/5/2013SERVICE VERSIONING 19
Big Bang approach

20. IN PRACTICE
 Most (web) service contracts are defined using WSDL & XML schema:
grammar-based
 Most changes are incompatible changes in grammar-based contracts
 Adding an optional field in the response is already breaking the contract!
 Updating a hardcoded XML namespace version number is breaking the contract!
 This results in a cascade of changes to be made by all clients using the
service
9/5/2013SERVICE VERSIONING 20

21. BELGIUM FEDERAL GOVERNMENT
EXAMPLE
9/5/2013SERVICE VERSIONING 21
Federal Service Bus
Agency 1 Agency 2 Agency n…
Authentic
Source 1
Authentic
Source 2
Authentic
Source
m
…
Different
organization
s

22. AUTHENTIC SOURCE VERSIONING
9/5/2013SERVICE VERSIONING 22
Crossroads
Bank for
Enterprises
Crossroads
Bank for
Social
Security
National
Register for
Person Data
…
• Single concurrent version
• Big-Bang versioning
• Version ID in xsd version attribute
• Single concurrent version
• Big-Bang versioning
• Version ID hardcoded in namespace
• Single concurrent version
• Big-Bang versioning
• Version ID hardcoded in namespace
Governance
very complex
due to island
culture

23. GOVERNANCE FSB
9/5/2013SERVICE VERSIONING 23
Federal Service Bus
Agency 1 Agency 2
Authentic
Source 1
Authentic
Source 2
Big Bang
versioning
Version mediation: limited to best-
effort version transformations
Shielded from the Big Bang in a best
effort

24. FROM BIG BANG TO MEDIATION
 Minimizing Big Bang scenario’s:
 Design by contract
 Contract first, rather than contract last
 Don’t hardcode version numbers in namespaces
 And don’t fix them in elements or attributes
 Use run-time versioning instead of design-time versioning
 Use rule-based, rather than grammar-based contracts
 Use governance and run-time mediation to connect
service versions, based on some version identifier in
the message
9/5/2013SERVICE VERSIONING 24

25. VERSION MEDIATION STRATEGIES
 Context-based routing
 URL selection
 Content-based routing
 Version ID
 Consumer ID
9/5/2013SERVICE VERSIONING 25

26. CONTEXT-BASED ROUTING
 Different endpoint for each version
 Routing decided by client
 New version:
 New proxy
 Consumer code change
9/5/2013SERVICE VERSIONING 26
Mediator Implementati
on
V1.0
Prox
y
V2.0
Prox
y
V1.1
Prox
y
Clients
V1.0
V1.1
V2.0
adapter

27. Mediator Implementati
on
V1.0
Prox
y
V2.0
Prox
y
V1.1
Prox
y
Clients
V1.0
V1.1
V2.0
adapter
CONTENT-BASED ROUTING
 Single endpoint for all clients
 Routing decided by service bus
 Client must pass version ID or client
ID
 New version: no impact to existing
clients
9/5/2013SERVICE VERSIONING 27
Service
Proxy

28. CONTENT-BASED ROUTING
Version ID Client ID
9/5/2013SERVICE VERSIONING 28
 Client sends a version ID it was
certified with
 Client decides which version to
use
 A version change implies a client
code or configuration change
 Client sends an ID to identify
itself
 Mediator decides which version
to use
 A version change has no impact
on existing clients

29. SERVICE USAGE AGREEMENT
 Create a Usage Agreement document for each client to define which
version is used.
 New service versions must take into account current version usage
9/5/2013SERVICE VERSIONING 29

30. THE CASE FOR STANDARDS
Archimiddle

31. VERSION STRATEGY AS A POLICY
 In principle, versioning can be handled by policies, just like security and
protocol policies like transactions and reliable messaging
 So, why is there no such policy?
 WS-Addressing is the closest thing
9/5/2013SERVICE VERSIONING 31

32. WS-VERSIONING PROPOSAL
 What we need is WS-Versioning
 Defines context-based and/or content-based version routing
 Defines SOAP header elements required for service version mediation
 End points, client identifiers, service version identifiers, …
 Abstract end point for mediator
 Ex.: https://services.myDomain.com/myService
 Specific end point only known by mediator
 Ex.: local://myService/v1
 Allows for dynamic binding to a specific version
9/5/2013SERVICE VERSIONING 32
v1
v2
mediatorclient

33. DYNAMIC VERSION BINDING
 Using endpoint URL in WSDL
 Abstract endpoint: https://services.myDomain.com/myService
 Using schema location URI in XML schema
9/5/2013SERVICE VERSIONING 33
<wsdl:service name=“MyService">
<wsdl:port binding="tns:MyServiceSoapBinding" name=“MyServicePort">
<soap:address location=“local:///MyService/v1" />
</wsdl:port>
</wsdl:service>
<xsd:import namespace="http://services/myDomain/myService/messages"
schemaLocation="./messages/myServiceMessages_v1.xsd" />
Dynamically bound

34. DYNAMIC VERSION BINDING
 Dynamic binding allows importing versioned schema’s directly from a
source control system, such as subversion, git, or UDDI service
repository
 Mediator should allow an extension like ?WSDL to the service endpoint
URL
 Examples:
 List of existing services: http://services.myDomain.com/myService?versions
 Picking the WSDL of a specific version: http://service.myDomain.com/myService?version=2
 Mediator decides whether to allow clients to pick older versions or not
9/5/2013SERVICE VERSIONING 34

35. CONCLUSION
Archimiddle

36. CONCLUSION
 Service contract versioning is a governance issue and not a development
issue
 Runtime versus design time
 Service contract versioning is simpler using rule-based service contracts
than using grammar-based contracts
 Using grammar-based contracts, most changes are incompatible changes
 Governance of service contract versioning can be supported by
 A mediator
 A repository
 And policy enforcement
 There is a need for a WS-Version standard for SOAP web services9/5/2013SERVICE VERSIONING 36

37. THE BALANCE
9/5/2013 37
GOVERNANCETECHNOLOGY

38. Contact
Ignaz Wanders
Archimiddle
Belgium
Ignaz.Wanders@Archimiddle.com
http://www.archimiddle.com/