c# - REST API 最佳实践 - 在现有 API 的请求/响应中添加新参数

Question

我正在使用 .NET 5.0。我目前在生产中部署了一个基于 REST 的 API，商家已经与它集成。现在有一个要求，我还需要在请求和响应中添加更多参数。

在现有的 REST API 中添加参数是不好的做法吗？我应该引入一个新版本，还是可以在同一版本中添加请求/响应参数？

编辑：附加参数不是强制性的

标签： c#apicompatibilityrestapi-versioning

Answer 1

API 可以在两个地方被破坏：请求（输入）和响应（输出）。

要求

如果您引入新的输入参数，并且希望在应用程序中保持向后兼容性，则：

1. 您的服务器端应该对缺少的输入参数有合理的默认值
2. 对于具有这些缺失值的输入，您的服务器端应用程序应该保持相同的行为（返回相同的输出，见下文）。换句话说，默认值（“回退”）足以返回相同的结果。

如果您不遵守上述规定，那么您的 API 在输入方面就被破坏了。

回复

响应很棘手，因为它取决于您的消费者以及响应的内容类型。

如果响应的内容类型是可扩展的，例如 JSON 或 YAML，并且您的 API 使用者知道可以随时将新字段添加到输出中并且可以忽略，那么您的 API 在输出条件。

但是，如果您的消费者期望响应中有一个严格的模式（例如，固定数量的现有字段），那么添加新字段（即使它们可以被忽略）是不可接受的，因此会破坏您的 API。

这取决于..

所以答案是：视情况而定。如果在输出中添加了新字段，那么您应该与您的消费者就扩展响应进行沟通，或者为您的 API 创建一个新端点 ( /v2/...)。

此外，如果输入参数没有合理的备用值，那么这同样需要v2API 的入口点。