Financial Market Data Web Services – Xignite Blog

Web service governance covers many topics one of which is change management. How do you change and enhance existing web services without breaking the code of your existing clients? After more than five years experience delivering web services to some pretty mission-critical applications, Xignite has learned a thing or two about what good business practices are in that domain. We use those rules internally when managing our services and we communicate those to our clients as well. These rules have worked well in helping prevent problems. We compiled those into the Ten Commandments below.

But let’s first remind what those Commandments seek to achieve:

1. Never break existing code. It’s pretty clear that clients that have already integrated their apps with your web service don’t like it when things stop working. They will be quite upset when they find out it is because you made a change without telling them (this happened to us with code we wrote against the famed API of a just-as-famous Saas CRM vendor).
2. Eliminate the need to update Existing code. Ideally, once clients have built something in, they should never have to change it. If that is impossible, the frequency and complexity of those changes should be kept to a minimum and clients should be given a time-frame to made those changes and multiple environments to test those changes against.

Ten Commandments of Web Service Change Management

1. Thou shalt never remove or rename a web service. This is pretty basic. If you change the location of the web service, all hell breaks loose. If you are going to rename a service, make sure you leave a proxy of the new one where the old one was.
2. Thou shalt never remove or rename a web service operation. With SOAP, the operation defines the SOAP action. With REST, the operation is part of the resource url. In either case, if your remove or rename the operation, the code will break. Because of the nature of web services, keeping “old” operations around for compatibility purpose is typically not a huge issue since only those clients using those operations are affected. We found it is a good practice to do so.
3. Thou shalt never rename a web service operation parameter. With SOAP, the operation parameters are part of the SOAP message. With
   REST, the operation parameters make up the resource url. In either
   case, the client code will break.
4. Thou shalt never add a web service operation parameter. Adding a new parameter to an operation will break your client’s code since that code does not currently pass that parameter. If the client uses REST, you may be able to add logic inside your web service to provide a default value for that new parameter, if the client uses the tighter-controlled SOAP, the code will break right away since it will never get passed the server and not even enter your code.
5. Thou shalt never remove a web service operation parameter. Removing an operation parameter is one of the lesser sins on this list. If the client uses REST, their code will most likely continue to work since the extra parameter will be ignored by your new service. If the client uses SOAP, the result will depend on the behavior of the client’s SOAP toolkit. Some may fail, some may ignore the additional parameters (For instance, client code written over .Net would continue working).
6. Thou shalt never remove an enumeration value on an operation parameter. Some
   values used as operation parameters are enumerations (i.e. a list of valid
   string values like ‘Daily’, ‘Monthly’, and ‘Annually’ could be the
   enumeration values of a member called PeriodType). Whether the client uses SOAP or REST, if the client code passes one of those values after you removed them from the valid list, their code will break.
7. Thou shalt never remove or rename a returned object member. Just like for #2 and #5, this is a very evil sin. If the client uses SOAP, their parser will break when not finding the member it is looking for. If the client uses REST, their code will only break if they use that parameter in their code. Either way, this one sends you straight to customer service hell.
8. Thou shalt never change the type of a returned object member. Although all data is exchanged over the wire as strings, changing the type of an object could have bad consequences based on the logic the client built on its side. For example, if you change type type of a field from Integer to Double, the code on the client side will probably choke on those decimals.
9. When adding new enumeration values on a web service member, make sure they are not returned by old operations. This is one of the trickiest rules on the list (and we found it the hard way). Note that adding new enumeration values is not a Commandment on the list. The reason is that new enumeration values are typically not returned by old operations.  For example if an operation value helps you identify a given type of interest rate or currency, if your client’s “old code” does not know about this value, it will never request it and never expose the problem. But if an “old operation” can return “new enumeration values”, the client’s SOAP parser will fail on trying to interpret those new unknown values. If this is functionality you need to have, you’d better turn those enumerations into strings.
10. Thou shall pray a lot before adding a new web service member. This is the only Commandment I wish did not make the list. The other ones make sense in a technical kind of way. This one really should not be. You should be able to add new web service members to your heart delight without anguishing over the consequences. After all, if a web service returns a new data element, the code on the other side does not know about it and should be able to simply ignore it. But the cold hard truth is that some parsers (Axis to be specific) will throw an exception when parsing new values returned by a service. The good news is that Axis plans to address this problem. The bad news is until then you will have to pray and notify your Axis users.