As developers, we know that software versioning is important. When we depend on an external library version releases notify us that fixes have been made, that new features have been developed, and that there are changes to the software that may require changes to our code if we want it to continue to behave correctly. There’s been a long standing approach to this in semver, which has been widely adopted by the node.js community with npm. We know this pattern works and works well for versioning software, but what about for versioning APIs?
Versioning APIs
Yunong Xiao spoke about semantically versioned APIs at Netflix in his Slaying Monoliths session at Node Interactive 2016. That session inspired me and the rest of the NBC team at Four Kitchens to investigate the idea further and study its viability for the application we were working on (and APIs in general). After many discussions and a few iterations, we’ve finally settled on a formalized version of our approach in semantic-api.
Using semantic API
Using a semantic-api server allows you to release changes to your API without breaking existing consumers—the whole intent of semver is to silo off changes that could cause problems. By strictly adhering to semver specifications you will never accidentally release a change that breaks existing consumers.
A semantic-api server also allows your consumers to construct “evergreen” requests that receive bug fixes and new features for free—semantic-api enables this by accepting npm-style semver ranges. So, for example, a consumer could request v1.0.0 in their application; as soon as v1.1.0 is released they will receive that new version of the API without needing to make changes to their codebase.
Machine versioning, human naming
If you choose to adopt semantic-api for your application, keep in mind that semantic versioned APIs that route via paths, e.g. /v1.2.3/blogs, can result in ugly URLs. That’s okay. URLs are for machines, not people, especially URLs that expose content APIs and are consumed by other machines.
Similarly, version numbers are also for machines rather than people. Jan Lehnardt touched on this in his talk at NodeConf London 2016, but the idea is that you should tie releases that are meaningful to humans to names that are meaningful to humans. If you follow this approach you could have the hot new stormtrooper version of your API which really contains versions v1.0.0, v1.2.3, and v2.0.0. Breaking the mental connection between the version number and the feature or application release is essential so that you don’t fall into a trap of not wanting to create a major version bump for a breaking change “because marketing says so.”
I’m very excited to see semantic-api’s implementation and adoption on NBC’s APIs and welcome feedback or questions about adopting it for your application as well! Please feel free to contribute to the specification.
Making the web a better place to teach, learn, and advocate starts here...
When you subscribe to our newsletter!