In a previous blog post I wrote about the necessity to plan your API life-cycle and especially the decommissioning of APIs and API versions due to breaking changes. I want to add some thoughts about why the idea to have no breaking changes ever is illusional.
Forces for Change
First, I want to outline forces that require changes to our APIs. These forces are in our environment, technology, security, and tidying up our mess.
Environmental Forces
There are many regulations and changes in laws and by external parties. For example, Europe introduced the Euro as a new currency and also unified bank account numbers. Prior to this change, online banking would look completely different and would be incompatible with our current way of making payment instructions. These changes happen regularly: our supplier might change the data format of certain fields or our API needs more information to validate data that are now required. All these things are beyond our control of technical API design and thus we cannot guarantee endless backwards compatibility for reasons that are not in our control.
Technological Changes
Technology develops quicker than ever. I started in the field when CORBA was supposed to save the world, before XML and Web services (SOAP) would save the world before RESTful HTTP and Web services (HTTP) would safe the world for sure. And yet, I have clients ask me how they can get rid of their file transfers and move their API clients over to an HTTP-based service. Technological changes often have a commercial and organizational component in it: of course, the client could still offer the file transfer but there are fewer and fewer people who know how to do it, employees are easier to get when they can work with newer technologies, offering two APIs with the same intentions is unnecessarily costly, and file transfers are inferior with regards to response times (although batching and larger payloads are usually easier). As such, breaking changes to the technology might also be required to fulfill newly quality criteria.
Security
Changes for security are a mixture of environmental changes and technology changes. Essentially, security is race between security measures like encryption and attack mechanisms like breaking existing algorithms and having more computing power available. Encryption algorithms are replaced by safer ones and the same is true for authentication mechanisms. Old standards cannot be supported because they would completely undermine the security improvements of the new standards and thus need to be discontinued.
Tidying Up & Technical Debt
When making changes strictly backwards-compatible it is often the case that the API contract gets bloated, names are getting awkward to keep them unique, and the developer experience for API clients degrades while maintenance costs for the API provider rise due to the complexity in the API contract and thus in its implementation. At some point it might be commercially viable to tidy up the API, include and straighten out everything we have learned of our business domain and our API clients, and release an incompatible API version.
The Web is not endlessly backwards-compatible!
Defenders of endless backwards-compatibility often cite the Web as their primary case study. While I find comparing the Web to APIs is comparing apples to oranges anyway because one is human interaction while the other is machine-to-machine communication, I still have to disappoint: The Web is in no way backwards-compatible. While I have been saying this for a long time I was proven right when I found my old Galaxy tablet from years ago. It booted up after I found the power connector and I was happily imagining how I would put this to use to surf the Web while I was not at my desk. However, after starting the browser I could not connect to any Web site. Web sites nowadays (correctly) require the use of HTTPS with current encryption and hashing algorithms which are not supported by the old browser. Because the tablet was too old there were no updates available anymore. If the Web had been backwards-compatible this wouldn’t have been a problem, but it isn’t.
There are many more examples of this: removing the alert() function in the browser in certain contexts for security reasons, various policies with regards to mixing content, no Flash support (a great relief) etc. have been put in place restricting existing usage. But even if people were just maximizing using new features (e.g., the <video> tag), users with older browser would see a Web page – but that page would be completely garbled and many functionalities (in case of YouTube even the core functionality of watching videos) would not be working.
So the Web isn’t backwards-compatible. But what is it? The Web essentially uses Aggressive Obsolescence: new features are introduced, and old features are deprecated before they are removed. Because browsers are constantly updated transparently over-the-air, users don’t see how the Web is technologically evolving.
TL;DR
Don’t let you fool you: There are many reasons why down the road of the life of your API there will be breaking changes. Prepare for them and do not pretend that all changes can be made in a backwards-compatible way. In a previous blog post I quickly introduced relevant design patterns.
If you want to see what your strengths and challenges with APIs are (and whether life-cycle is one of them) I want to invite you to use our free API questionnaire. After making 18 clicks you will better know where to proceed in your API journey!
|
<<< Previous Blog Post Camunda 7 Message Events and Optimistic Locking |
Next Blog Post >>> API Patterns help you with Life-Cycle Management |