Web Service Versioning


Published on

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

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Explain that versioning is a governance issue that must be controlled, but its origin is in the technical implementation of the service contract. Technical versioning implementation has a direct consequence for governance.
  • These two principles are coupled to one another.
  • Authentic source: a unique source for data with particular value for the government.Examples: National Register for person dataCrossroads Bank for Social SecurityCrossroads Bank for EnterprisesAll different organizations, each with their own rules and own standards
  • All authentic sources follow a Big Bang versioning strategy.Notification of a change usually is performed by sending e-mail around.
  • The Federal Service Bus allows for some versioning issue shielding caused by the authentic source’s versioning scheme.However, because any AS only supports a single concurrent version, for incompatible changes, version transformations alone cannot do the trick.
  • 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
    16. 16. GOVERNING SERVICE VERSIONS Archimiddle
    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.: 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. 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. 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. 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 Ignaz.Wanders@Archimiddle.com http://www.archimiddle.com/