<story><title>API versioning has no “right way” (2017)</title><url>https://apisyouwonthate.com/blog/api-versioning-has-no-right-way</url></story><parent_chain></parent_chain><comment><author>cletus</author><text>I have to disagree somewhat: versioning objects or endpoints is never the right solution. I&amp;#x27;d go so far as to say that versioning the whole API is simply the least bad option.&lt;p&gt;What constitutes a major version? Simple: as soon as existing clients break it&amp;#x27;s a new major version. That means you can, for example, add new endpoints because that&amp;#x27;s not a breaking change. You simply can&amp;#x27;t remove or change any of the existing endpoints, fields or objects.&lt;p&gt;It also means that a client can&amp;#x27;t mix-and-match what major versions to use ie you can&amp;#x27;t use &amp;#x2F;v1&amp;#x2F;customer and &amp;#x2F;v2&amp;#x2F;account. Why? Because clients will do that as a quick hack and you need to save them from themselves.&lt;p&gt;So why not version endpoints or objects? Because of environment bifurcation. Let&amp;#x27;s say you have 2 API versions (v1 and v2). To verify your API you can test each independently. That&amp;#x27;s relatively easy.&lt;p&gt;But imagine you have 10 endpoints and each is versioned separately. Now you have to test 2^10 possibilities. Clients will do stupid things like use a different version as a quick hack or even when they don&amp;#x27;t need to and you&amp;#x27;ll be debugging those things forever. Don&amp;#x27;t give your API users footguns.</text></comment>
<story><title>API versioning has no “right way” (2017)</title><url>https://apisyouwonthate.com/blog/api-versioning-has-no-right-way</url></story><parent_chain></parent_chain><comment><author>hn_throwaway_99</author><text>I liked this article, but after trying many different approaches in the past, I&amp;#x27;ve found that GraphQL&amp;#x27;s &amp;quot;evolvable&amp;quot; approach is by far the best. And while the author correctly points out that some REST APIs have used this approach for a while, there are a couple important things that make this approach really easy to use in GraphQL:&lt;p&gt;1. When you deprecate fields, they disappear from the &amp;quot;default&amp;quot; documentation in the Graphiql browser. Which means it&amp;#x27;s always easy to see the latest &amp;quot;version&amp;quot; of the API.&lt;p&gt;2. Since &lt;i&gt;clients&lt;/i&gt; request fields, you don&amp;#x27;t feel like you&amp;#x27;re unnecessarily returning an object that&amp;#x27;s twice as big as it needs to be with all the new and deprecated fields in the same response.&lt;p&gt;3. Corollary to #2, but since clients request fields it&amp;#x27;s easy to detect who hasn&amp;#x27;t migrated and who is using deprecated fields, which makes it easier to notify these clients or at least make an informed decision about when you can remove deprecated fields.</text></comment>