Don't have an account? Join now...

Versioning the mod.io API

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.

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:

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.

In this News

Only registered members can share their thoughts. So come on! Join the community today and join in the conversation.

You are not logged in, join the community or sign in with your social account: