I am working on a team that is developing the server side API for a mobile application. The API is evolving as we go and we have released several iterations of the API and mobile app. We have clients using the app in production and we can’t always guarantee the clients will be on the latest version of the app. This means we need to maintain previous api endpoints so the older versions of the app don’t break.

How does thoughtbot handle versioning of mobile client apis? We try to avoid creating new versions unless we are requiring new parameters or have to change the response format. Here are a few ways we’ve thought maintaining versions.

/endpoint-version_number - The way the app is currently written is each endpoint has it’s own version number appended to it. Usually the mobile just uses the latest version of an endpoint, but it can get messy where you have /users3 and /merchants5. The one benefit I see to this is if you make a breaking change on one endpoint, you don’t have to bump the version number of the entire api

/v2/endpoint - I like having the version number in the url because you can version the api as a set and say that we’re using version X of the api. However, if you have a breaking change to one endpoint, then you have to bump the entire version of the api. If you’re doing iterations on your server side and mobile app, I could see quickly getting up to v7 or v10 which means you have a lot of endpoints to maintain. Also, if you introduce some new functionality or a refactoring and want to backport it to all of the previous versions of the api. I wonder if this scheme would introduce some headaches too.

Any insight or best practices of how to handle internal apis for mobile applications would be greatly appreciated. Please let me know if there are other versioning practices I haven’t thought of.

Thanks,

-Aaron