API版本控制没有“正确的方式”
API版本控制是一个非常困难的主题，有时被视为一个卑微的辩论。它在不同的公司中的不同方式，不同公司内的不同偏见通常会有所不同。
有些人从方法A移动到接近B，当方法B解决他们的特殊问题时，他们表现得像是喜欢B是＆＃34;最好的＆＃34;没有人应该是USEAPPROAP A.这一切都很好，直到他们实现方法C可能是Agood的想法。
版本传感器有很多方法，它可能很难进行Talkabout - 更不用说理解 - 他们所有人，但我将尝试创建一个adefinigitive指南。
在工作中，我是任务的推荐一个方法到API版本控制，因为现在我们有一个方法的混合方法，我们正在使用最糟糕的可能方法的一些微妙级别。我的建议和研究是对所有你所有人的指南。
通常在路径中（例如，/ api / v1 / companies），这可能是子域（例如，API-v2.foo.com/companies）。如果要求迫使API更改公司的代表性的功能，即使用户根本没有改变，也会创建一个新版本的整个API。
通常这些是计划定时版本，其中 - 例如 - API的IOSApp和V2的V2是定时部署，V1可能有日落日期。
这里的缺点是很少发生变化清晰。在我们的示例中，当用户没有改变时，客户端开发人员有一个粗略的时间记住。此外，对于偷偷摸的更改，因为＆＃34;这是一个重大释放，这是改变东西的时候，这是非常常见的。通过该命令集，API开发人员非常容易推出梅图所得沟通或记录的更改。
有些公司通过诚实的情况来避免这种情况，并且在新服务器上的新型API应用程序，新域名具有新的API应用程序。他们构建http://new-api.example.com，或者使用代号名，然后抛弃旧。最终，一旦旧货机达到了可接受的低或零用法，他们就会将旧DNS黑洞。
这有利于您离开时遗弃的遗产，但无论使用什么名称，版本号，还是其他任何东西，构建多个API并强迫客户端在新版本之后持续开发新版本，这不是版本控制的最耗时的方法，而不是只是apidevelopers，但客户开发人员也是如此。每个人都必须测试Oneach新升级的一切，这一切都是永远的。
在/ API / V1 /公司和/ API / V1 / USER的相同示例中，如果Company offeruld，那么可能会创建A / API / V2 /公司，但是/ API / V1 / USER仍未受到影响。这使客户更容易升级Asthey知道在哪里关注他们的注意力。如果用户没有v2，则他们刚刚使用V1。
这种方法的一个问题看起来几乎与外部的全局版本平均相同，而不是。
我看到使用API :: V1 :: BaseController，API :: V2 :: BaseController和API :: V3 :: BaseController构建的应用程序，每个都有自己的错误格式。在全球版本中完全完全罚款，因为假设是客户威尔斯的所有V1，所有V2或所有V3。在资源版本中，客户端在任何时间都可以选择V1，V2和V3端点，这意味着它们需要支持三种不同的错误格式。
一个最终用户应用程序产生错误的错误，如错误：[对象对象]交换最终用户，因为JavaScript代码预计V2格式{＆＃34;错误＆＃34; ：＆＃34;一些消息＆＃34; }，但{＆＃34;错误＆＃34的v3错误; ：{＆＃34;消息＆＃34; ：＆＃34;某事＆＃34;，＆＃34;代码＆＃34; ：＆＃34; er-123＆＃34; }}已经回来了。
我们可以根据使用标准错误响应响应所有系统（向RFC 7807对HTTPAPI的问题详细信息喊叫），但这只是修复了更大问题的onesyMptom。
这种方法非常相似，但不是在URL中的版本控制，版本GoIn接受和内容类型标题。
将URL问题脱颖而出，避免了API开发人员错误地分析了Version特定基础控制器的惯例。这是一个很长一段时间的多当版本控制（我所包括的身高），并且是Github很长一段时间的方法。
它保持相同的端点工作了很长时间，但如果标题isoptionalions会导致混淆。如果客户端不请求特定版本，如果他们得到最早支持的版本，还是最新的？
如果添加了V3并且v2最终被弃用，则客户端宁愿突出启动一个可能破坏其应用程序的全新版本。
我曾经看到过这种在Wework的这种方法，但我相信它是诸如其他地方的浓度。这是＆＃34的变体;资源版本控制（基于URI）＆＃34;，在没有版本的整个资源中，只有该方法的方法。
这很难出于充分的理由包围你的头。让我们看看它如何令人作呕：
最新＆＃34;取代所有＆＃34;对于公司可能是GET / API / V2 /公司，但为您可能发布/ API / V3 /公司的公司，即使GET / API / V3 /公司不存在。资源甚至没有保证匹配相同的方法，因为方法+ URI是什么使其成为唯一的是，所以get / api / v1 / companies / {id}可能是抓取单个资源的最佳方式，谁知道那些资源Serializers是一样的。
这拥有前面提到的解决方案的所有缺点，近几个云端。
主要是，API开发人员习惯了一次性端点。每个时期B需要更新资源，他们创建自己的新方法，Ignorethe现有方法，这是由于缺乏实现方面的策略，这是正常的。
一次性端点思维导致了创建新更新MethodShave的情况，其中仅包含早期更新方法功能的子集。 API开发人员添加功能是不知道以前版本中的功能，并且没有担心看起来＆＃34;无论如何都没有升级。＆＃34;
由于这种分歧，即使客户端想要升级，他们也无法捕获它们，它们被困在旧版本上，然后必须永远支持，旧版本必须使用较新的端点来打破客户端。
这种增加的功能基本上询问所有API团队支持比他们应该的功能更加功能，而那就是斯普定的时间和金钱。
API Evolution是从不违反您的合同的概念，直到youbolsolutelly必须，然后您可以管理对客户的致密警告更改。它不是关于制作任意变化和破坏的东西。
一般来说，您添加新字段，或添加新资源，如果您绝对不能弃用，并且当它不再使用时，最终可以撤消旧位。
这是目前被GraphQL推广的方法，而是重建于几十年来谈论的方法。在HttpEvolution上进行了一系列伟大的写作，于2012年在2012年进行，最近在API长长的MageMagement上的优秀帖子。
Evolution不是GraphQL功能，而是一个在大多数类型的API中工作的概念。
在以前的公司提供众包，我们只添加了字段，切勿删除它们。这对大多数宽度来说很好，但是当向后兼容问题绝对不能被标记时，我们利用了一个概念的商业名称，并抓住了我们的API与商业名称相匹配。
匹配是驾驶员和乘客之间的关系，并且多重算法将构成拼车。 BC的变化是添加多个驱动程序，它完全拧紧匹配的概念。当我们从/乘客切换到/ riveers时，我们完全更改了JSON表示，这两个表示共享相同的代码。
几个月后，贬值的概念被贬值了，客户始终开始新的骑手的概念。内部的改变了多次，因为我们对新目标进行了重新编码，我们将与骑手转换为骑手，那么文本匹配只是一个不同的串行器坐在骑手顶部。在此过程中，合同从未改变过。
我们经历了几个背面来实现这一点，但我们的客户不需要做一件事，除了切换到＆＃34;骑手＆＃34;在自己的时间。 Android和iOSApps独立推出，这根本没什么重要的。
进化方法将一些额外的工作推向API开发团队，但避免了将类似的工作量推向客户团队。如果Oneapi有5个客户端，那么我们正在节省5倍的开发，测试等。
无论您是使用全局URI版本控制，还是想要使用Evolution，您都需要考虑如何处理弃用。
如果您的团队足够小，您只需通过电子邮件发送IOS开发人员，并建议使用较新的端点，或者更新的整个Damn API，但如果您使用数百名开发人员（和30多个服务！）在Acompany工作，这可能不会效力方法。
在Wework中，我们构建了一个名为We-Callthat的法拉第包装器（流行的Ruby HTTP客户端），迫使使用中间件的PowerOf上的客户端和服务器的一些良好约定。
其中一个公约是在使用静止草案日落标题的句法糖，使用了annotations，使其超级简单。您无需使用整个We-Call Gem，您只能使用Faraday-Sunset，或者如果您可以使用Guze-Sunset。
您可以向人类宣传田地正在与Openapi和它的＆＃34;弃用＆＃34;关键字，在v3.0中添加。这远非完美，因为没有计算机检测这些折旧，而无需向OpenAPI模式Intoshe JSON响应即可迁移链接。
JSON Schema正在处理添加本，并且对于将JSON模式链接放入JSON响应，它更常见。 fornow，不要删除任何字段，只需添加新字段，并使用您真正无法处理旧合同的新代表。
PayPal Dothisfors他们的API，但他们正在使用预先约会的供应商扩展名为OpenApi'Depecated功能。
条纹已经概述了一种让他们的公众可爱的方法，这是高于聪明的方式。它们而不是使用HTTP / In-Band Metadata宣传它的事实，而是构建迁移迁移，将旧请求转换为新闻界内部。
它们以一定时间兼容迁移，将其保留向后兼容，通过电子邮件向客户端发送电子邮件，在此之前，将客户开发人员提供一整群。
这是由Facebook完成的几年，然后在他们在路径中扔进了全球版本的全部和培训的所有内容......
基于URI的大多数版本控制是薄薄的RPC，只需看起来有点恢复。如果使用RPC命名约定的公司正在进行基于URI的版本控制，那么API将更像这样：
如果人们将其API设计为RPC，并且只需承诺成为RPC API并为特定客户提供的终端，他们已经在实际上已经做了。
诚实地对此。隐藏虚假意图，RPC，文档ASSUCH，也许只是使用GRPC。
API Evolution是令人难以置信的功能，如果您投入工作以使其成为可能。致力于努力，更容易让事情变得更加容易，特别是JSON Schema带来了在Future中弃用。
全球URI版本控制是最不可思议的替代方案。我只推出无法承诺合同的团队，并建立令人难以置信的差异，以匹配令人难以置信的应用程序的迭代（例如，V1，V2，移动应用程序）。也许只需使用每个版本的代码符并删除Oldapis，而不是尝试将其全部堵塞到一个代码库中，并在另一个版本中更改了某些共享代码的潜在棕色版本。
无论哪种方式，全球版本都没有完全依赖，并提示散步，这是从罗伊直接来的。
基于资源的内容协商如果您有一些非常http-sevvyclieser并令人难以置信地记录您的意图，但它基本上是ashortcut，有点演变，这并没有真正添加任何好处。
为爱的意大利面条怪物的爱，请不要做任何基于方法的版本控制。它永远不会有任何意义。您正在为每个人制作意义，分裂期望，创造开销和聚焦短期收益和长期混乱。
然而，您决定版本，只要您使用少数几个莫比语方法之一，请记住它不是决定哪个是＆＃34;最好的＆＃34;它的分享和理解各种方法的优缺点和缺点，以及基于该信息的教育决策。
