Web services and backward compatibility

About a year ago I was asked by a client to update their existing web service because of some changes in the way they wanted to process their sales data. Luckily this client has always understood the importance of a Service-Oriented Architecture ( SOA ) since they deal with large amounts of resellers who need to access, edit and create data. All I had to do was apply the changes to their web service.

I decided to move forward by using the following steps.

  1. Assess if the desired changes are backward compatible
  2. If not, assess if support for the old functionality is still required
  3. If yes, design and implement the changes so that both the old and the new functions are supported concurrently
  4. Decommission the old functions after a pre-defined grace period

Most of the changes were backward compatible but, as always, there were some obstacles. For some backward incompatible changes I was able to add optional data structures.

// Old function
function create_account($name, $street, $postcode, $city) { ...

// New function with added optional variable 'country'
function create_account($name, $street, $postcode, $city, $country = null) { ...

For other functions I was able to call another function at the end of said function. This left pre-existing records untouched and, most importantly, the users of the webservices didn’t have to update their code.

Also some of the functions became obsolete so I decided to relay their functionality to newer functions and have them throw an exception stating that the function was replaced and soon to be deprecated.

The most important change however was making the decision to implement versioning for the clients web services. I advised the client to contact all it’s resellers via a mailing to inform them of the 1.0 version ( the version we had just updated ) of the web service. In the same mailing the client also mentioned it’s desire to update the service every 9 months and that every version of the service would be decomissioned 6 months after the introduction of it’s successor.

This made my job really easy because I only had to worry about backward compatibility for one version. Luckily almost every reseller went on this ‘journey’ with us. Of the 200+ users of the webservice only 3 didn’t update on time over the last year. Now I just implement all the desired changes once every 9 months and I provide the resellers with a detailed changelog and instructions for updating.

However, the most beautiful result of all is; a happy end for all parties involved.

Author: Luc De Brouwer

Luc is a web developer who loves WordPress, Magento, PHP, MySQL, HTML, CSS, jQuery, good food and Nine Inch Nails.

7 thoughts on “Web services and backward compatibility”

Fatal error: Call to undefined function the_comments_navigation() in /var/www/vhosts/thepersistenceofloss.com/httpdocs/wp-content/themes/twentysixteen/comments.php on line 49