1

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.

ian
  • 12,003
  • 9
  • 51
  • 107
Basit
  • 1,830
  • 2
  • 31
  • 50
  • Did you look at the links in the Related sections to the right? For example [this one](http://stackoverflow.com/questions/389169/best-practices-for-api-versioning?rq=1) – Paaske May 20 '14 at 08:04
  • Some of them are too complex for me at this point. – Basit May 20 '14 at 08:17

1 Answers1

0

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...

Roy Dictus
  • 32,551
  • 8
  • 60
  • 76
  • Thank you for your response. I failed to mentioned that the RESTful API is not public. It will only be consumed by mobile applications for a foreseeable future. It is private, too so only registered API keys could access its resources. But I still think that keeping a backward compatibility is a good idea for publicly available mobile apps too. Because outdating a functionality and asking users to update the app would piss them off, too. Now, if I support a functionality, would I not have to keep the resources, too? That means keeping a `v0.2` folder and all the resources it required. – Basit May 20 '14 at 08:14
  • I agree, keep the same "version" by adding to the existing functionality for as long as possible. If you need to change the API, create a new version and "deprecate" the old one, but don't remove it. Keep it around and give developers 3-6 months to get up to speed. Also I think 3xx is better than 4xx when an API has been replaced. – Paaske May 20 '14 at 08:27
  • Thank you for your response, @Paaske. But, you see, I am not making a publicly consumable API. It'll only be consumed by my mobile applications. How do you suggest I keep the backward compatibility of the API? Moreover, the 404 would automatically be thrown by the server as it can't locate the file if I change the version of the directory it resides in. – Basit May 20 '14 at 10:29
  • 1
    Ok, but you still shouldn't change the old folder, just add a new one. Then you'll have the two folders available for a while, until all your users have updated to the latest version of your app (which is now using the newest version of your API). Then you can remove the folder with the old version. – Paaske May 20 '14 at 10:43
  • Doesn't it create maintainability issue? I would not only have to maintain separate files and directories for each version, but also multiple versions of, say a configuration file. Seems to me like a hectic solution. – Basit May 20 '14 at 11:52
  • Basit, you keep old versions around for backwards compatibility. Normally, you should not "maintain" a previous release -- it's just there. – Roy Dictus May 20 '14 at 11:55
  • And how do I go about it? Keep separate directories and files for each version? What about a resource that's changed in the new version, say a function `fetch_records` is now optimized/modified. In the case of keeping all the files, I would have to keep that function, too. And in general, keep different instances of entire resources. – Basit May 20 '14 at 18:05
  • Basit, read the answers again, your questions have already been answered. – Roy Dictus May 20 '14 at 18:36