Versioning Best Practices
Background: Versioning Libraries
I’m assuming most readers here will be familiar with Semantic Versioning, but if not, a quick summary is that changes to the version number indicate the size of the change, depending on the digit that is changed, working to a major.minor.patch pattern.
The objective behind this numbering is to help with dependency management. A developer of software with dependency on a sematically versioned library is given some understanding of the likely impact of updating that dependency to a new version by looking at what digits have changed between the current and new versions.
Specifically, a change to the major digit is very important, as it indicates a major change that is incompatible with contract provided by previous version, and so it is expected that migration work will be required for the application to continue to work with the new library.
Versioning REST Services
Unlike libaries, where the precise version needs to be specified 1
- An Increment to the the third digit (
z)indicates a patch, with no functionality change - Incrementing the second digit (
y) means that a minor enhancement has been made, compatible with existing clients and usage. - A
This document is based on assumptions on the upgrade lifecycle of the system.
All the server instances get upgraded at the same time and all run the same version.
Client versions get upgraded at their leisure, but never get ahead of the minor version supported by the server. (If major version, then client needs to negotiate versions until it finds one that is supported.
Evolving Requests
Fields
| Modification | Allowed | Notes |
|---|---|---|
| None –> Optional | Yes | |
| None –> Mandatory | No | 2 |
| Optional –> Mandatory | No | 2 |
| Mandatory –> Optional | Yes | |
| Mandatory –> None | No | 2 |
| Optional –> None | Unlikely | Only possible if clients using the field able to support changed responses. |
Data types
Changing request data types can be achieved by adding a new (optional) field with the data type, deprecating the old field, processing that in preference to the old field on the server. On version upgrade, make the new field mandatory and remove the old one.
Data values
Adding a new enumeration
Server can add support for new enumeration options
Removing an enumeration
Removing unused enumerations should only be done as part of major version-change cleanup.
Evolving Responses
Field Names
| Modification | Allowed | Notes |
|---|---|---|
| Addition | Yes | |
| Removal | No | Major version only 2 |
Data types
Changing response data types may be possible if the text representation is interchangable between the values, and that the new value can be coerced into the old type. Otherwise, the change must be made by adding a new field with the new data type. On version upgrade, remove the old old field.
Data values
Adding a new enumeration
Depends on several different factors involving the role of the field and the client implementation.
- If the new enum is only rendered in response to a request attribute submitted but the client, the new value can be added
- If clients’ implementations might fail if the response value is not in the list of enum values, it should not be added
- If the clients are expected to be able to process the response as If the client is expected to perform further pro
Removing an enumeration
Assuming that there is no other data in the response(s) that might be tied to this enum, it is safe to remove it.
Footnotes
-
Library dependencies do not always need to be specified using a precise version number, but instead the latest compatible release can be selected. See TBD ↩
-
Major Version Change Only: versioning can be achieved either by including a version in the URL, adding a header, or versioning the content-type name. ↩ ↩2 ↩3 ↩4