rest api_如何使REST API向后兼容

rest api

代表性状态转移，通常称为REST，是一种体系结构样式-一组约束，用于实现在HTTP上运行的无状态服务。 RESTful API是符合REST约束的API。 您可以使用许多不同的编程语言来构建RESTful API。

保持API不同版本之间的向后兼容性对于确保API与使用该API的所有客户端保持兼容至关重要。 本文讨论了如何在RESTful API中保持向后兼容性。

[InfoWorld的要点： CI / CD入门：使用CI / CD管道自动执行应用程序交付 。 • CI / CD的5个常见陷阱-以及如何避免这些陷阱 。 | 通过InfoWorld的App Dev Report新闻通讯了解编程方面的热门话题。 ]

API兼容性示例

假设您在生产中拥有一个供不同客户端使用的API。 现在，如果要向API添加更多功能，则应确保使用旧API的客户端将能够使用新API或旧API。 换句话说，您应该确保在添加新功能时，API的现有功能将保持不变。

如果可以与该API的一个版本一起使用的客户端（编写使用该API的程序）可以与该API的未来版本以相同的方式工作，则该API向后兼容。 换句话说，如果客户端应该能够无缝使用新版本的API，则API在各个发行版之间向后兼容。

让我们通过一个例子来理解这一点。 假设您有一个名为GetOrders的API方法，如下面的代码片段所示。

[HttpGet]
[Route("GetOrders")]
 public IActionResult GetOrders(int customerId, int orderId = 0)
 {
   var result = _orderService.GetOrdersForCustomer(
                 customerId, orderId);
   return Ok(result);
 }

GetOrders操作方法接受客户ID和订单ID作为参数。 请注意，第二个参数orderID是可选的。 下面给出了GetOrdersForCustomer私有方法。

private List<Order> GetOrdersForCustomer(int customerId, int orderId)
{
   //Write code here to return one or more order records
}

如果作为参数传递给它的orderId为0，则GetOrdersForCustomer方法返回客户的所有订单。如果orderId不为零，则返回与作为参数传递的customerId所标识的客户有关的一个订单。

由于GetOrders操作方法的第二个参数是可选的，因此您只需传递customerId。 现在，如果您将操作方法​​GetOrders的第二个参数更改为必需参数，则旧的API客户端将无法再使用该API。

[HttpGet]
[Route("GetOrders")]
 public IActionResult GetOrders(int customerId, int orderId)
 {
   var result = _orderService.GetOrdersForCustomer
                 (customerId, orderId);
   return Ok(result);
 }

而且，这正是您可以破坏API兼容性的方法！ 接下来的部分讨论了可以使API向后兼容的最佳实践。

API兼容性提示

现在我们知道问题的根源了，我们如何以推荐的方式设计API？ 我们如何确保RESTful API向后兼容？ 本节列出了在这方面可以遵循的一些最佳实践。

确保单元测试通过

您应该编写测试，以验证该功能是否在新版本的API中完好无损。 应该以这样一种方式编写测试：如果存在任何向后兼容性问题，它们应该失败。 理想情况下，您应该具有用于​​API测试的测试套件，该套件会失败并在API向后兼容问题时发出警报。 您还可以将自动测试套件插入CI / CD管道，以检查向后兼容性并在发生违规时发出警报。

永远不要更改HTTP响应代码的行为

您绝对不要在API中更改HTTP响应代码的行为。 如果您的API在无法连接到数据库时返回500，则不应将其更改为200。同样，如果在发生异常时返回HTTP 404，并且您的客户端正在使用它和响应对象来确定发生了什么错误的方法是，更改此API方法以返回HTTP 200将会完全破坏向后兼容性。

永不更改参数

当您进行较小的更改时，避免创建新版本的API，因为这可能会过大。 更好的方法是向您的API方法添加参数以合并新行为。 同样，您不应从API方法中删除参数，也不应将参数从可选参数更改为强制参数（反之亦然），因为这些更改将破坏API，并且旧客户端或API使用者将不再能够使用API​​。

版本化您的API

API版本控制是一个好习惯。 版本控制有助于使您的API更灵活并适应更改，同时保持功能完整。 它还可以帮助您更好地管理对代码的更改，并且如果新代码引起问题，则可以更轻松地还原为旧代码。 在每个主要版本中，您应该具有不同版本的RESTful API。

尽管REST没有提供有关API版本控制的任何特定指导，但是您可以通过三种不同的方式对API进行版本控制：在URI中指定版本信息，在自定义请求标头中存储版本信息，以及将版本信息添加到HTTP Accept标头。 尽管版本控制可以帮助您维护API，但应避免尝试维护许多版本的API以标记频繁发布的版本。 这将很快变得麻烦且适得其反。

其他API最佳做法

您永远不要更改API的根URL或修改现有的查询字符串参数。 任何其他信息都应作为可选参数添加到API方法中。 您还应确保永远不会删除传递给API或从API返回的可选或强制性元素。

更改RESTful API是不可避免的。 但是，除非遵循最佳实践并确保API向后兼容，否则所做的更改可能会破坏API与现有客户端的兼容性。 生产中并由多个客户端使用的API始终应在各发行版之间向后兼容。

翻译自: https://www.infoworld.com/article/3401920/how-to-make-your-rest-apis-backward-compatible.html

rest api