How to be a good web service? Breaking changes of web services and how to manage them?

Breaking changes in web service are those changes that may cause the client to change behavior.

What changes are be breaking changes?

Not all the updates of the web services are breaking change. Breaking changes are those changes that will enforce new customer behavior. There are three types of changes are breaking changes. 

I The addition of  mandatory parameter. 

For example, at the cashier of a grocery store, customer previously only need to slide the credit card, sign the receipt to check out. One day, the store manager decide to check the security code on each credit card in addition to obtaining a signature from customer. This change of the checkout process is a breaking because it will enforce customer to get the security code of the credit card. 

II. Change the response of existing request

For example, the grocery cashier decide not to give customer receipts during checkout as before, this will confuse the customer. It is a breaking change because customer who have code path depending on existing response may have to be updated to accommodate the new response.  

What changes typically are not breaking?

Changes that does not require customer to change client code are not breaking change.

a. The addition of optional parameter. 

Typically, adding optional parameter would not require client code to change. 

b. The removal of mandatory parameter.

When the mandatory parameter is removed, as long as the existing client code path still function as before, it is not a breaking change. 

c. The addition of a new service end point.

When a new web service end point is added, the change is not breaking.  

How to manage breaking change?

a) Convert a breaking change to a non-breaking change. 

Technical wise, all the breaking change can be converted to non-breaking change by addition of new service end point ( type c). However, due to all kinds of reasons, sometime, adding a new service end point is not an option, for example, OData protocol has a defined set of REST end points, if you want to change some behavior of those end points, it is not advisable to add new end points from scratch. 

b) API versioning 

API versioning provides more flexibility of introducing breaking change. Basically, at the HTTP header, the server mandate client to specify a version header, with each version of the service end points, the server behavior does not change. When breaking changes are introduced, the service end points behavior are retained as long as the version header of the request specify previous version. 

c) Communication. 

If neither a) nor b) is an option, you can still try to be a good web service provider by proactively communicate with your customer starting by the following line. " I am really really sorry that we are planning to introduce some breaking change of our API in the next release....

Comments

• Anonymous
  May 23, 2013
  You glossed over II of breaking changes. It is certainly backwards incompatible to remove an existing field from the response.  But the addition of a new optional field to a response is not considered breaking. In your example, if that cashier also asks the customer if they'd like to open up a store credit card account, the existing relationship is not broken and the customer's code must be written so that ignoring the new optional parameter does not break their client code.

• Anonymous
  September 12, 2013
  Thanks for your great information, the contents are quiet interesting.I will be waiting for your next post. <a href="www.allinonewebservice.com/">Web development Company in india</a>