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.
Asked
Active
Viewed 1.7k times
3 Answers
15
You should check out this presentation about API design. It's from Google and pretty good. It also addresses backward compatibility and new releases.
Peladao
- 4,036
- 1
- 23
- 43
-
http://lcsd05.cs.tamu.edu/slides/keynote.pdf << broken link :( – kinar May 17 '16 at 19:10
-
2and yet still broken, maybe this is the one? http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf – user180574 Jul 01 '16 at 19:32
-
Link is broken. – Salar Nov 19 '16 at 09:51
-
Thanks @user180574. I edited my answer and put in the new link. – Peladao Nov 25 '16 at 16:45
8
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.
Rene Pot
- 24,681
- 7
- 68
- 92
-
3That'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 09:07
-
There is some discussion whether you can still call it a REST api if you include versioning in the url scheme. see http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven or http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html – Jeroen Coupé Jan 18 '12 at 09: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 09:22
-
@Sampat if you like an answer (as a best answer) please mark it that way – Rene Pot Jan 18 '12 at 09: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
-
Some API guidelines, like the one from Zalando, prohibit the use of a version in the URL. How would you go about it then? – Dormouse Oct 17 '18 at 07:12
-
@Dormouse this is about creating an api, not using one. In that case, when there is backwards compatibility change they'll warn you about it, or create a new API. – Rene Pot Oct 17 '18 at 10:28
-
When creating an API you also have to take this into account, right? Either way, a correct answer is you could create a new endpoint with the same uri, with a different media type. http://www.springboottutorial.com/spring-boot-versioning-for-rest-services is a good resource. – Dormouse Oct 17 '18 at 10:59
3
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.
Asraful
- 1,241
- 18
- 31