Wednesday, November 19, 2014

Think Twice Before Changing your APIs

How often do you make changes to a service that actually alter the API itself? I'm sure if I asked this question to an experienced developer the answer would follow something along the lines of "You would NEVER want to do that! If you change the API, you risk breaking any applications that are consuming that service." As this danger is fairly well known, how do you guard against it?

Imagine this scenario: there is a set of web services that are being consumed by multiple web applications. The API for one of these services has been changed so that a service method that was taking a string, is now taking an integer. Unfortunately, this little change caused the contract surrounding the service to also change, which meant that any applications consuming it would also need to be updated. It wasn't until another application started to throw exceptions that it became clear that one had been missed.

If this was a new area of development, a contributing factor to this oversight could have been that the developer making the change might have not known that the contract they were changing was already being consumed by multiple applications. The developer might have assumed that it was OK to change the contract because the code was "very young" and it couldn't have been integrated with other applications in such a short time frame. If anything this highlights why you can’t rely on a developer to catch this as they can't be expected to know of where each service method is being used.

The fix is simple, but could this have been avoided in the first place? A simple solution would be to never alter the API of a service, ever. The problem with this is that it is still comes down to the developer to ensure that this is being followed. Remember that in my example, the service method had been only been created very recently so it's conceivable that another developer would also assume that they were dealing with the only occurrence where the service method was being consumed. Documentation and improved communications between developers would help to identify an issue, but it would still be up to the developer to notice it.

An ideal solution would be automated so that a developer would not need to be aware of how an API is being consumed. If this could be created as a set of tests that are run as part of a build process, any issues would be identified well before deployment to production. To achieve this, you would need the ability to stage the service in a test environment where you could fire off requests to verify that the API has not changed. Another possibility would be to compared the current WSDL file with a previous version to check for changes.

If you find yourself considering altering an API, be sure to take a moment to ask yourself why. Can you extend the current contract to ensure that the API will not be broken instead of changing it? In most cases, this should be the preferred course of action and making changes to the contract should only happen when there really is no other choice.