RESTful API Versioning

Question

I'm a new to RESTful API's and sort of developing my first one at the moment for a mobile application to be followed. I have a question regarding API versions and how to manage/tackle them.

At this moment, my API 'version' is a directory named v<version_name> in which my API class resides. In that directory, I have resources that the API and REST client needs in another directory named include . So the structure is as follows: example.com/api/v0.2/method_name/ and on .htaccess , I'm making sure that everything that follows the API version (hardcoded in the .htaccess file, is saved in a query string parameter). I'm not sure if it is the right approach for a live application as it requires manually changing the URL endpoints at clients' ends, too. So my questions are:

1. Is this the right approach to API versioning?
2. If it is and I keep it, how do I deal with outdated URL's. Say for instance the app is live and I update the API to v0.3 but the client who have the app installed would be accessing v0.2 and getting a 404 response code back?
3. Is there more elegant solution out there? It must be.

Edit: there are some resources that reside outside of the api folder itself, in the root include folder so to speak.

Edit 2: My API is targeted to be consumed by mobile applications and is not publicly consumable.

Answer 1

While I think these questions are primarily opinion-based, I will have a go...

1. I think it is a valid approach, and I've seen others use it, including Microsoft.

2. When it is necessary to outdate an API, you could give a 404 back with an explanation that the new API is at the new address. HOWEVER it is usually a bad idea to just retire an API version; you would at least have to give client developers enough time to switch to the new API before retiring the old, if at all.

3. A more elegant solution would be to just keep the API at one address, and update that as necessary, and add to it rather than replace whenever possible. Keep supporting outdated functions for as long as possible and have open communication to client developers about when a certain method will no longer work.

Just my opinion, do with it what you will...