Take the 2-minute tour ×

Are there any best practices to keep in mind while designing API's which ensures backward compatibility and new version releases. Any links to articles/blogs is appreciated.

share|improve this question
add comment

3 Answers

up vote 4 down vote accepted

You should check out this presentation about API design. It's from Google and pretty good. It also addresses backward compatibility and new releases.

How to Design a Good API and Why it Matters

share|improve this answer
add comment

keep both running, with version in the url. api.mysite.com/[version]/api/url/here. Notify the users when a new version of the API arrives, and drop the old version after a while. Either when it isn't used anymore, or like 6 months insuring the users had enough time to change it.

Or keep it running forever, but don't deliver any new functionality for it.

share|improve this answer
That's basically the approach I've used on multiple projects. One other pattern I've seen very often is to have api.example.com/ point to the latest version of the API - notice the lack of a version number. Clients who don't want the latest and greatest are free to hit the versioned URL - api.example.com/v1/ –  Anurag Jan 18 '12 at 9:07
There is some discussion whether you can still call it a REST api if you include versioning in the url scheme. see roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven or thereisnorightway.blogspot.com/2011/02/… –  Jeroen Coupé Jan 18 '12 at 9:18
Thanks. These are more towards versioning the API's and deployment of those. I am interested in knowing if there are any guidelines on how to expose the API's, what happens if your data schema changes(you delete/modify some datatypes which are exposed through the API's etc) –  Sampat Jan 18 '12 at 9:22
@Sampat if you like an answer (as a best answer) please mark it that way –  Rene Pot Jan 18 '12 at 9:45
@Anurag In the approach which you suggested, if i point to the latest and implement my end point solution and may be down the line your new version API are released on the same URI and you version your current live to /vn/ then there are still chances of breaking the endpoints? –  Sampat Jan 19 '12 at 10:23
add comment

The best way to do this to keep the old interface or class in new release with new interface and classes and marked them as deprecated (means those will be removed in future release).

Hear API designer keep in mind about difference between public interface and published interface.

share|improve this answer
add comment

Your Answer


