The content of the following article comes from some content compiled when I was working on the API interface before. I will record and share it.
In the early days of HTTP and HTML, there was a rule that any browser encountering an unrecognized element or element attribute should act as if the tag did not exist. This makes it possible to quickly update the functionality of HTML without increasing the "destructibility" of the HTML client application (browser). (Note: See Bert Bos's 2001 talk on "W3C, XML, and Standardization " for some insight into early HTTP/HTML design.)
All similar examples can be traced back to a basic rule that guides the creation of most Internet standards themselves. The "robustness principle " proposed by Jon Postel in 1980 :
" Be conservative in what you do, be liberal in what you accept from others ."
The first rule of properly managing long-term changes to your API is not to commit breaking changes to production . The reason is simple: once you publish your API and people start using it, the interface is a promise. And breaking that promise could mean losing customers. As Amazon's Werner Vogels said: "APIs are forever". He said in a 2016 blog post ,
"[At Amazon] we know that designing an API is a very important task because we only have one chance to do it well."
3 rules for API interface backward compatibility
There are some simple implementation rules you can use to reduce the likelihood of introducing disruptive changes in your API ecosystem. It's important to make these part of your API design and review practices if you want to successfully manage your APIs in the long term.
Rule One: Don’t take anything away.
The first rule is that once you publish an API, you can't take stuff away from it. You can't take away a promised URL, an input parameter, or an output data point . Even if you tell developers in your documentation that certain elements of your API may disappear or change, you still can't do that. Because, well, developers.
The truth of this first rule is explained in what is known as " Hirum's Law " or "Law of Implicit Dependence":
"With a sufficient number of API users, it doesn't matter what you promise in the contract: all observable behavior of your system will be relied upon by someone." - Hyrum Wright, employee software engineer at Google.
This also works for enumeration values. If you have a field called status and record that it has five possible values, you can't later publish an update to the API when status only has four possible values.
Rule Two: Don’t change the meaning of anything.
The second rule states that you cannot change the meaning of existing elements in your API . If the count parameter in your promise filter statement refers to "number of users", then you cannot change the same parameter to "number of pages" later.
Changing the meaning of something has the same effect as taking it away and replacing it with something else. That's a breaking change and an abandonment of your Hippocratic Oath to the API.
Rule 3: All new features are optional.
The third rule is that any new functionality (URLs, input parameters, and output parameters) must be considered optional. If your addCustomer operation took four required parameters in the original version, you cannot add a new, fifth required parameter. Again, this essentially takes away the old addCustomer method and replaces it with a non-backward-compatible version of addCustomer.
Of course, there are situations where you have no choice but to introduce a breaking change. Maybe your team screwed up and the API exposed personally identifiable information, or some regulations changed and you're no longer allowed to accept or share data, etc. When this happens, it's time to take out your split ends. Because a new "version" of an API is really just a fatal fork (in software terms).
Forking is a fairly well-known term in software engineering. It dates back to online discussions via Usenet in the early 1980s, and refers to the creation of a branch off the trunk of a project. The assumption was that once you branched off your fork, you no longer expected to merge back to trunk. While we often use trunk, branch, and merge in software engineering today, APIs tend to "remain forked" over time and are rarely merged back together.
If you know you need to introduce a breaking change, fork your API and publish it in a new URL space. Call it a "version" if you like. But you're still not James Bond, so be aware that releasing a new version doesn't mean you can kill the old one. Instead, you need to run them side by side for a while. This avoids the whole "middle finger" situation we mentioned earlier.
With side-by-side APIs, API consumers can continue to use their current API version until they are ready to upgrade at some point in the future - their own timeline, not yours.
Salesforce is a company that knows very well how to fork APIs for fun and profit. They have a habit of releasing a new version of the API three times a year. Their Spring 2021 API is version 51. Last time I checked, they support all previous versions, going back to Spring 2014 (aka v30!). Yes, Salesforce supports 20 past versions, side by side.
Open source champion Eric S. Raymond associates "forks" with tragic or costly events. Creating a software fork usually indicates an irresolvable split and means a lot of duplication of effort. And, as we saw with the Salesforce model, the same is true in the API world.
If you work on releasing breaking changes, you also need to work on side-by-side releases, documentation, online support, etc.
