35

This page lists the following examples:

  • Addition of new WSDL operations to an existing WSDL document
  • Addition of new XML schema types within a WSDL document that are not contained within previously existing types

But is there a definition or standard guideline for what changes are considered backwards-compatible. Or in other words, what changes can you make to your contract, and still expect not to break your clients.

Asbjørn
  • 1,212
  • 1
  • 11
  • 15

2 Answers2

57

I have spent some time on this particular subject, and found some guidelines in a book by Thomas Erl which I refer to at the bottom. Here is what they have to say;

Compatible Changes

  • adding a new WSDL operation definition and associated message definitions
  • adding a new WSDL port type definition and associated operation definitions
  • adding new WSDL binding and service definitions
  • adding a new optional XML Schema element or attribute declaration to a message definition
  • reducing the constraint granularity of an XML Schema element or attribute of a message definition type
  • adding a new XML Schema wildcard to a message definition type
  • adding a new optional WS-Policy assertion
  • adding a new WS-Policy alternative

Incompatible Changes

  • renaming an existing WSDL operation definition
  • removing an existing WSDL operation definition
  • changing the MEP of an existing WSDL operation definition
  • adding a fault message to an existing WSDL operation definition
  • adding a new required XML Schema element or attribute declaration to a message definition
  • increasing the constraint granularity of an XML Schema element or attribute declaration of a message definition
  • renaming an optional or required XML Schema element or attribute in a message definition
  • removing an optional or required XML Schema element or attribute or wildcard from a message definition
  • adding a new required WS-Policy assertion or expression
  • adding a new ignorable WS-Policy expression (most of the time)

There is a great book on this particular subject from Thomas Erl et al; The name is Web Service Contract Design & Versioning for SOA.

HTH.

Disclaimer: As I've mentioned, this is work done by the authors of the book and I'm merely sharing it. I'm also not affiliated in anyway; just liked the book :)

Selim
  • 1,013
  • 9
  • 15
  • 10
    Hello, I think item 4 'adding a new optional XML Schema' is not backward compatible in the absolute. It it is only for Request Messages. If your client apply best practices and enable XSD validation at runtime on the XML response, then any new optional tag will be rejected. Please comments – Aerosteak Apr 05 '12 at 12:46
  • 3
    I agree with Aerosteaks comment. The backward compatibility should be modeled as a matrix with three columns: something like TypeOfChange, IsRequestMessageBackwardCompatible, IsResponseMessageBackwardCompatible – nize Sep 25 '12 at 14:02
  • 2
    It's also possible to achieve forward compatibility by adding to the end of your responses. With this they can be extended in the future. But that's something which shouldn't be overused. – Turbokiwi Sep 25 '14 at 09:33
  • 1
    Are there client( librarie)s that would check the WSDL at runtime and fail if it were changed, even if the changes are backward compatible? – David Balažic Sep 29 '15 at 20:50
5

Additional optional request elements (minoccurs=0) could also be backward compatible - this depends on the implementation of the service on the host side. Also, changing a mandatory response element to optional could also be backward compatible - it depends on the implementation of your client.

This area is tricky.

If you are really worried about backward compatibility consider creating a new version of the service for new clients and keep the existing implementation for existing clients. Also, in general, avoid sending domain objects over your services - use DTOs.

Hope this helps.

Nick Ryan
  • 2,662
  • 1
  • 17
  • 24
  • yes it appears to be a grey area. I would consider adding optional parameters backwards compatible too. Just wondered if there some general agreement on changes you could make and still expect clients too work. True, one could always a new version, but I would prefer to avoid this if it wasn't necessary. – Asbjørn Jan 09 '12 at 11:34
  • I don't know of a standard document or general agreement that defines what you can get away with and still support backwards compatibility. Even if you did have one for the WSDL, the underlying implementation still has to support it (I guess I'm saying that the WSDL doesn't necessarily in itself tell a consumer the full story about how a service should be used and what to expect in the response). If I were you, and I wanted to guarantee backwards compatibility, I'd implement a new version of the service. – Nick Ryan Jan 09 '12 at 13:01