I marvel at the debate that takes place about when to create a new version of an API, HTML, or REST resource. In a world where being combative or argumentative is the norm, here is some guidance and ammunition for those looking for sanity when creating a new version.
Any time a parameter is added or changed on the input or output of a method, the version should be changed. The version change is also a courtesy to developers utilizing the method—hey something was added or changed, so take note.
When a method changes either through a name change, additional functionality, or through deprecation a new version, is necessary.
Sometimes it’s necessary to move a method or REST resource to a new location because of an architectural, semantic, categorization, or physical server consideration. When the location of an API method changes, always create a new version and add a warning to the existing API method that the method was moved to a new location, and all future calls should be directed to the new location.
Technology Implementation Change
Technology changes. Frameworks, languages, and new programming techniques are often catalyst for changing the implementation of an API. The changes usually result in a speed increase, better quality, or more functionality. When the technology used to implement a technology changes, it’s a good idea to inform the user via a version change.
There may be times when the results returned from a method call are augmented or modified but are not useable. For example, if the results expected are for an address of 50 characters, but the results now include 70 characters and an office suite number the calling programs may not be able to handle the result.
To execute a successful implementation, you must have a practical versioning scheme. Without a versioning strategy, an API and the associated functionality becomes difficult to scale and deploy.