<story><title>Best practices for API versioning?</title><url>http://stackoverflow.com/questions/389169/best-practices-for-api-versioning/</url></story><parent_chain></parent_chain><comment><author>waterside81</author><text>As others have alluded to, it&amp;#x27;s all fine &amp;amp; dandy to try to adhere to the guidelines of &amp;quot;pure REST&amp;quot; but in reality, you have customers&amp;#x2F;users who know enough to construct a web request, but don&amp;#x27;t &lt;i&gt;really&lt;/i&gt; understand what HTTP verbs are, what HTTP headers are etc. In my experience, your average developer (of course, not anyone who&amp;#x27;d frequent HN!) really doesn&amp;#x27;t have a good grasp of how HTTP works. So the way you combat this problem is either&lt;p&gt;1) You provide client libraries in the popular languages so your users can download those and not have to make requests directly. This way you can put versioning and accepted response types in the headers instead of the URL&lt;p&gt;OR&lt;p&gt;2) You put everything in the URL and you&amp;#x27;re done with.&lt;p&gt;In my company, we initially went with 1) but then realized that just putting a version &amp;amp; format (.json, .xml etc.) in the URL lead to much fewer &amp;quot;Your API isn&amp;#x27;t working&amp;quot; emails.</text></comment>
<story><title>Best practices for API versioning?</title><url>http://stackoverflow.com/questions/389169/best-practices-for-api-versioning/</url></story><parent_chain></parent_chain><comment><author>LukeB_UK</author><text>The top answer seems to have the mentality of &amp;quot;screw the consumer&amp;quot; when it comes to versioning. If you have someone using version 1 of an api, when you decide to make it version 2, you&amp;#x27;re essentially breaking their app by having the reference change to the new one.&lt;p&gt;The answer even touches on the subject that it should be a permalink, yet they then say that a new version should be the same url as the old one, which means it&amp;#x27;s not a permalink! In my view, this is madness and potentially breaking for people using your api.&lt;p&gt;In my personal opinion, you should set out with versioning in mind from the start, otherwise by making even a slight change to your api, you change what the consumer receives, potentially breaking stuff.</text></comment>