Behind the scenes at mod.io we have been slowly determining the best road forward in regards to versioning our API which we recently concluded and announced. You would think this is a simple decision, but there are multiple ways to do it, each with their own pros and cons and amongst the wider community there doesn't appear to be any clear standout when it comes to how your API handles versioning - so much so that popular security personality Troy Hunt weighed in on the matter conceding all three options had issues.
Our requirements
The key to our eventual versioning decision was a flexible versioning scheme, that would allow us to push breaking changes at no detriment to our API consumers that ticked the boxes for both development convenience, reliability and familiarity.
- Full backwards compatibility
- Version is required in every request
- Clear version progression with changelog
- Easy to get up running and make API requests and test
- Ability to deploy breaking changes without impacting API users
First decision: version in URL vs HTTP request header
Option 1: Version in URL | Option 2: Version in HTTP request header 'Accept' |
---|---|
Used By
Pros
Cons
|
Used By
Pros
Cons
|
Our choice: version in URL
We value developers more than anything, so we wanted the version to be easy to see and test by simply copying and pasting a URL into your web browser. We opted against requiring a version header, because this approach forces API developers to write code or use a tool to get up and running.
Second decision: version format
Option 1: v1, v2, v3 |
Option 2: MAJOR.MINOR.PATCH |
Option 3: YYYY-MM-DD |
Option 4: YYYYr{0-9} |
---|---|---|---|
Used By
Pros
Cons
|
Used By
Pros
Cons
|
Used By
Pros
Cons
|
Used By
Pros
Cons
|
Our choice: v{0-9}
We wanted a version format that clearly shows when a change was made and forces us to really think about minimizing breaking changes to our API which would require a new version. We felt that including the version number provides amazing clarity, and allows developers to know how many versions they are behind.
Demonstration
A game is currently making HTTP requests like so:
GET https://api.mod.io/v1/games/5/mods
We release an important update that removes a field expected from objects within this response, thus a breaking change. The game should not be impacted due to our API change, so the developer of the game views the changelog for the version, see's what changed - makes appropriate changes within the game client to accommodate for this release, then simply upgrades their base URL to include the latest version.
GET https://api.mod.io/v1/games/5/mods
Conclusion
As a business we want to move quick and continually update and improve our service to give developers the most powerful mod API on the market. Achieving this will require breaking changes from time to time, so minimizing the impact to our API consumers by really thinking through our versioning system was critical.
We believe the solution we have arrived at balances this need well, for the following reasons:
- Developer convenience as it uses a popular, familiar and convenient versioning scheme.
- Developer confidence that our breaking changes will never affect their application.
- The version is explicit, and hard to miss. You always know what version you are using.
- When making requests with an
api_key
during the prototyping phase, you can easily copy and paste code snippets that work. No headers to worry about. - Enables us the freedom to evolve our API without worrying about affecting existing API consumers.
For more information on how we version the mod.io API, be sure to check out our new changelog section of the documentation. Thanks for reading!
Comments
No comment were found matching the criteria specified. We suggest you try the comment list with no filter applied, to browse all available. Join now to participate.