Post news Report RSS Versioning the mod.io API

Choosing a versioning system for an API used by game clients, web apps and consumers that balances backwards compatibility with clarity and ease of use is not easy. Here's how we did it for mod.io.

Posted by on

Behind the scenes at mod.io (an API for developers to support mods in-game) 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 - read on for our requirements and eventual decision.

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

Version in URL or HTTP request header

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 from our documentation 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, and instead chose to require the version be explicitly included in all URLs calling the API.

https://api.mod.io/{YourApiVersion}/games?api_key={YourApiKey}

Version format

There are a surprisingly large number of version formats in use by the industries largest APIs. Common ones include:

  • Option 1: v1, v2, v3
  • Option 2: MAJOR.MINOR.PATCH
  • Option 3: YYYY-MM-DD
  • Option 4: YYYYr{0-9}

We wanted a version format that clearly shows when a change was made, how many changes have been made and only increments when a breaking change is deployed. We felt that including the year solved the first requirement, and including a release number solves the final two requirements, allowing developers to know how many versions they are behind.

https://api.mod.io/YYYYr{0-9}/games?api_key={YourApiKey}

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. If you are interested in implementing mod.io API in your game, we'd love to talk to you and have included a deck below with a little more information about it.

Post a comment

Your comment will be anonymous unless you join the community. Or sign in with your social account: