如何进行API 版本控制

链接：www.postman.com/api-platfor…

作者：postman

原标题：API versioning

什么是API版本控制？

API版本控制是管理和跟踪对API的更改的过程。它还涉及将这些更改传达给API的使用者。

更改是API开发的自然组成部分。有时，开发人员必须更新其API的代码以修复安全漏洞，而其他更改则会引入新的特性或功能。有些更改根本不会影响使用者，而另一些称为“破坏性更改”的更改会导致向后兼容性问题
，例如意外错误和数据损坏。API版本控制可确保成功推出这些更改，以保持消费者信任，同时保持API安全、无错误和高性能。

在这里，我们将回顾API版本控制的好处，并讨论几个需要版本控制的场景。我们还将探讨API版本控制的一些最常见方法，提供成功版本控制API的五个步骤，并强调API版本控制的一些最佳实践。最后，我们将讨论Postman API平台如何支持你的API版本控制工作流。

API版本控制有什么好处？

随着API的发展，API的生产者和消费者必须保持同步，无论它是私有的还是公共的。有效的API版本控制策略不仅使API生产者能够以最小化破坏性更改对消费者的影响的方式进行版本控制，而且还提供了一个框架，用于将这些更改有效地传达给消费者。这种透明性建立了信任，并且在公共API的情况下，增强了组织的声誉，这可以提高API的采用率和保留率。

应该在什么时候对API进行版本控制？

每当你进行需要使用者修改其代码库以继续使用API的更改时，都应该对API进行版本化。这种类型的更改被称为“破坏性更改”，可以对API的输入和输出数据结构、成功和错误反馈以及安全机制进行更改。一些常见的破坏性更改示例包括：

• **重命名属性或终结点：**你有时可能希望重命名属性或方法，以便其含义更清晰。虽然从API设计的角度来看，明确的命名很重要，但是一旦API投入生产，就几乎不可能在不破坏使用者代码的情况下更改属性或方法名称。
• **将可选参数转换为必需参数：**随着API的发展，你可能会注意到某些输入参数应该是强制性的，即使它最初被设计为可选参数。虽然这种类型的更改可能有助于标准化输入并使API操作更可预测，但对于未编程为传递此属性值的客户端，它将导致丢失属性错误。
• **修改数据格式或类型：**你可能有时会意识到，多个属性（如firstName和lastName）应该存在于用户对象中，而不是作为接受字符串值的单独属性。虽然这种类型的更改会改进API的设计，但它仍然是一个会导致解析异常的破坏性更改。
• **修改属性的特性：**你可能偶尔会尝试更改某些属性的规则。例如，类型为：string的描述属性可能具有你发现过低或过高的maxLength规则。这种类型的更改将根据其实现而产生不同的结果，包括数据库和UI错误。

API版本控制有哪些类型？

API版本控制有几种方法，包括：

• **URL版本控制：**使用这种方法，版本号包含在API端点的URL中。例如，有兴趣查看数据库中所有产品的消费者将向 https://example-api.com/v1/products 端点发送请求。这是最流行的API版本控制类型。
• **查询参数版本控制：此策略要求用户在API请求中包含版本号作为查询参数。**例如，他们可能会向 https://example-api.com/products?version=v1 发送请求。
• Header版本控制：这种方法允许使用者在API请求中将版本号作为Header传递，这将从URL结构中删除API版本。
• **基于消费者的版本控制：这种版本控制策略允许消费者根据自己的需求选择合适的版本。**通过这种方法，使用者第一次调用时存在的版本与使用者的信息一起存储。以后的每一个调用都是针对同一个版本执行的–除非消费者显式地修改了他们的配置。

重要的是要注意，这些版本化策略与版本化方案（如语义版本化或基于日期的版本化）一起使用。语义版本化遵循三部分数字格式（即，3.2.1），其中第一个数字表示可能包含重大更改的主要更新，第二个数字表示包含新的向后兼容功能的更新，第三个数字表示错误修复或补丁。相比之下，基于日期的版本管理使用发布的具体日期来标识版本。

如何对API进行版本控制？

API版本控制直接影响API的整体成功，需要仔细规划以确保以有条不紊的方式执行。API生产商应遵循以下步骤，尽可能有效地对其API进行版本化：

步骤1：选择版本控制策略

在API生命周期的API设计阶段，选择API版本控制策略非常重要。这个版本控制策略应该在你的投资组合中的所有API之间共享。越早考虑版本控制，就越有可能选择弹性设计模式，以减少破坏性更改的发生。尽早决定API版本还将帮助你的团队在现实的路线图上保持一致，以确定你的API将如何发展以满足未来几年的消费者需求。

步骤2：确认是否需要新版本

变更是API开发过程中不可避免的一部分，但并非每次变更都需要一个新版本。在决定推出新版本之前，团队应该评估他们想要进行的更改的范围和影响，并确定是否有方法以向后兼容的方式进行更改。例如，你可以选择添加新操作，而不是修改现有操作。如果没有办法避免突破性的变化，你可以考虑等到你发布了一个令人兴奋的新功能，这将改善你的消费者的体验。

步骤3：更新文档

如果你已经决定是时候对API进行版本化了，那么更新API文档以包含有关版本的信息是很重要的。例如，你需要传达更改背后的原因，它们将如何影响消费者，以及如何访问新版本。你可能还希望包括一个发布时间轴和迁移说明-特别是如果你计划最终弃用旧版本。

步骤4：逐步部署新版本

只要有可能，团队应该分阶段发布新的API版本，从一小群用户开始。然后，他们应该收集这些用户的反馈，并在更广泛地发布新版本之前解决任何问题。此方法可帮助团队验证新版本是否按预期工作，并提供有关真实的使用者如何与API交互的宝贵见解。

步骤5：废弃旧版本

一旦新版本稳定，团队应该监控采用情况，以评估有多少用户成功迁移。如果采用率符合预期，团队可以创建并宣布弃用旧版本的时间轴。此时，为继续使用旧版本的用户提供支持非常重要，因为他们可能需要帮助过渡到新版本。

API版本控制的最佳实践是什么？

随意的API版本控制方法可能会对API的消费者和生产者造成负面影响。以下最佳实践将帮助你避免潜在的陷阱，并确保API版本控制策略的成功：

• **设计时考虑可扩展性：**在API设计过程中，从战略上考虑版本控制非常重要。例如，某些数据类型，如布尔值和原子数组，比其他类型更容易受到破坏性更改的影响，因此最好尽可能从API设计中省略它们。
• **了解你的消费者：**当你决定是否进行更改时，了解你的消费者是如何使用你的API的是很重要的。这涉及到意识到不可见的API契约，它指的是你的API的意外实现。例如，使用者可以通过对象的索引而不是属性名来访问对象中的属性。虽然这种实现不是API的生产者所期望的，但是在版本控制过程中应该考虑到它。
• **在服务条款中包含版本控制策略：**让你的消费者知道你将如何定义重大更改、何时警告他们即将发生的更改以及他们需要多长时间才能迁移到新版本，这一点很重要。这种做法对于合作伙伴和公共API至关重要，尤其是那些货币化的API。
• **解耦实现版本控制和契约版本控制：**在版本控制方面，将API的实现与其契约分开考虑是很重要的。例如，如果你在Rust中重写了Node.js实现，但合约没有更改，则不应发布新版本的API。
• **彻底测试：**版本控制是API生命周期中的一个主要事件，因此尽一切努力确保它顺利进行非常重要。在开发和部署过程中进行彻底的测试有助于确认新版本按预期工作，而不会给用户带来任何新问题。
• **计划弃用：**在开发新版本的API时，考虑如何以及何时弃用旧版本是很重要的。这涉及建立弃用策略，将弃用计划传达给消费者，随着弃用日期的临近监控旧版本的使用情况，最后删除其服务器和文档。仔细的弃用计划和沟通可以降低意外风险，防止旧实例运行太长时间，并确保消费者有足够的时间过渡到新版本。