Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Web Service Versioning

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:

  • Be the first to comment

Web Service Versioning

  1. 1. SERVICE VERSIONING 25/09/2012 Service Technology Symposium London Ignaz Wanders, Archimiddle The Balance Between Service Governance and Service Technology
  2. 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. 3. THE PROBLEM OF CHANGE Archimiddle
  4. 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. 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. 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. 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. 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. 9. SERVICE VERSIONING Archimiddle
  10. 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. 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. 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
  14. 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. 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
  17. 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. 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. 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. 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. 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. 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. 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. 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. 25. VERSION MEDIATION STRATEGIES  Context-based routing  URL selection  Content-based routing  Version ID  Consumer ID 9/5/2013SERVICE VERSIONING 25
  26. 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. 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. 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. 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. 30. THE CASE FOR STANDARDS Archimiddle
  31. 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. 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.:  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. 33. DYNAMIC VERSION BINDING  Using endpoint URL in WSDL  Abstract endpoint:  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. 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:  Picking the WSDL of a specific version:  Mediator decides whether to allow clients to pick older versions or not 9/5/2013SERVICE VERSIONING 34
  35. 35. CONCLUSION Archimiddle
  36. 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
  38. 38. Contact Ignaz Wanders Archimiddle Belgium