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....