Web Service Versioning

SERVICE VERSIONING25/09/2012

Service Technology Symposium

London

Ignaz Wanders, Archimiddle

The Balance Between Service Governance and Service Technology

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

THE PROBLEM OF CHANGE

Archimiddle

04/13/2023Service Versioning 4

A SERVICE LANDSCAPE

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?

04/13/2023 5

1: COMPATIBLE CHANGE

SERVICE VERSIONING

Service X

Client 1

Service Z

Client 2

Client 3 A compatible change allows service clients to use the new version transparently

Service Zv2

New compatible version


2: INCOMPATIBLE CHANGE

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 Zv2

New incompatible version

Service Xv2


GRADUAL CHANGE

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 Zv2

New incompatible version

Service Xv2


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

time

Old version

New version

Transition period for client upgrade

SERVICE VERSIONING

Archimiddle


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


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

xx.yy.zzz


STRATEGIES

In practice, most service changes are incompatible changes! So the strategy is less important; you get a new major version anyway

Strategy

New major New minor New point

Strict Incompatible change

Compatible change

Flexible Incompatible change

Compatible change

Loose Incompatible change

SERVICE VERSION COMPATIBILITY

Archimiddle


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

COMPLEX!

So nobody does this…

Including functional aspects!


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

GOVERNING SERVICE VERSIONS

Archimiddle


DESIGN TIME VERSUS RUN TIME

Design-time versioning Run-time versioning 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


TECHNOLOGY VERSUS GOVERNANCE

Technology Governance

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


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.)

Big Bang approach


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


BELGIUM FEDERAL GOVERNMENT EXAMPLE

Federal Service Bus

Agency 1

Agency 2

Agency n

…

Authentic

Source 1

Authentic

Source 2

Authentic

Source m

…

Different organizations


AUTHENTIC SOURCE VERSIONING

Crossroads Bank for

Enterprises

Crossroads Bank forSocial

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


GOVERNANCE FSB

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


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


VERSION MEDIATION STRATEGIES Context-based routing

URL selection

Content-based routing Version ID Consumer ID


CONTEXT-BASED ROUTING Different endpoint for each version Routing decided by client New version:

New proxy Consumer code change

Mediator Implementation

V1.0 Prox

y

V2.0 Prox

y

V1.1 Prox

y

Clients

V1.0

V1.1

V2.0

adapter


Mediator Implementation

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 clientsServiceProxy


CONTENT-BASED ROUTING

Version ID Client ID

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


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

THE CASE FOR STANDARDS

Archimiddle


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


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

v1

v2

mediatorclient


DYNAMIC VERSION BINDING Using endpoint URL in WSDL

Abstract endpoint: https://services.myDomain.com/myService

Using schema location URI in XML schema

<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


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

CONCLUSION

Archimiddle


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 services

04/13/2023 37

THE BALANCE

GOVERNANCETECHNOLOGY

ContactIgnaz Wanders

Archimiddle

Belgium

[email protected]

http://www.archimiddle.com/

Web Service Versioning

Technology

Transcript of Web Service Versioning