Category Archives: Lessons Learned

Beware of changing variable names in SOAP Webservices

When improving upon your SOAP webservices currently in production, it might occur to you to change variable names in method signatures to make the more readable and conform to your coding practices. After these are the small incremental improvements we make to reduce our technical debt. But before doing this, please beware of the ramifications.

A WSDL describing a SOAP webservice is “strongly typed” in the sense that method signatures including method names, variable names and their types, once defined, cannot be changed with breaking backward compatibility. And Since SOAP does not provide an easy way for clients to detect an API change, altering either of the constructs that define your WSDL guarantees a temporal disruption of service due to your current API consumers.

For example, say you have a SOAP webservice exposing this method:

public Report GetReport(string ReportName)

which is defined as part of your WSDL. If you later change this this method to say

public Report GetReport(string reportName)

the service will receive null as the reportName in some client implementations. Others may simply crash since this endpoint is no longer known. If one is spending quite some time working with SOAP based services on a daily basis, it becomes almost of a second nature to regenerate the client proxy based on the published WSDL to ensure consistency otherwise, you get these strange behaviors. However, if you are spending a lot of time in RESTFul services, chances are you are not worrying about these types of problems. In this case, there is a good chance you will rename a webservice API parameter name in the name of improving readability (nothing wrong with that) only to find out that the next morning none of your clients are able to connect to your API.

And no, unit tests will not catch this.