REST API 最佳实践 - 在现有 API 的 request/response 中添加新参数
REST API best practice - adding new parameters in request/response of existing API
我正在使用 .NET 5.0。我有一个基于 REST 的 API 目前部署在生产环境中，商家已经与它集成。现在有个需求，我需要在request和response中也多加几个参数
在现有 REST API 中添加参数是一种不好的做法吗？是应该引入新版本，还是在同一个版本中添加req/response个参数就可以了？
编辑：附加参数不是强制性的
API 可以在两个地方中断：请求（输入）和响应（输出）。
请求
如果您引入新的输入参数，并且希望在您的应用程序中保持向后兼容性，那么：
- 您的服务器端应该为缺少的输入参数设置合理的默认值
- 您的服务器端应用程序应该为具有这些缺失值的输入保持相同的行为（return相同的输出，见下文）。换句话说，默认值（“回退”）足以return相同的结果。
如果您不遵守上述规定，那么您的API在输入方面有问题。
回应
响应很棘手，因为它取决于您的消费者以及响应的内容类型。
如果响应的内容类型是可扩展的，例如 JSON 或 YAML，并且您的 API 消费者知道可以随时将新字段添加到输出中，并且可以将其忽略，那么你的 API 在输出方面是向后兼容的（即没有损坏）。
但是，如果您的消费者期望响应中有严格的模式（例如，固定数量的现有字段），那么添加新字段（即使它们可以被忽略）是不可接受的，因此会破坏您的 API.
这取决于..
所以答案是：视情况而定。如果将新字段添加到输出中，那么您应该与您的消费者沟通有关扩展响应的信息，或者为您的 API (/v2/...).
创建一个新端点
此外，如果输入参数没有合理的回退值，那么这又需要 API.
的 v2 入口点
我正在使用 .NET 5.0。我有一个基于 REST 的 API 目前部署在生产环境中，商家已经与它集成。现在有个需求，我需要在request和response中也多加几个参数
在现有 REST API 中添加参数是一种不好的做法吗？是应该引入新版本，还是在同一个版本中添加req/response个参数就可以了？
编辑：附加参数不是强制性的
API 可以在两个地方中断：请求（输入）和响应（输出）。
请求
如果您引入新的输入参数，并且希望在您的应用程序中保持向后兼容性，那么：
- 您的服务器端应该为缺少的输入参数设置合理的默认值
- 您的服务器端应用程序应该为具有这些缺失值的输入保持相同的行为（return相同的输出，见下文）。换句话说，默认值（“回退”）足以return相同的结果。
如果您不遵守上述规定，那么您的API在输入方面有问题。
回应
响应很棘手，因为它取决于您的消费者以及响应的内容类型。
如果响应的内容类型是可扩展的，例如 JSON 或 YAML，并且您的 API 消费者知道可以随时将新字段添加到输出中，并且可以将其忽略，那么你的 API 在输出方面是向后兼容的（即没有损坏）。
但是，如果您的消费者期望响应中有严格的模式（例如，固定数量的现有字段），那么添加新字段（即使它们可以被忽略）是不可接受的，因此会破坏您的 API.
这取决于..
所以答案是：视情况而定。如果将新字段添加到输出中，那么您应该与您的消费者沟通有关扩展响应的信息，或者为您的 API (/v2/...).
此外，如果输入参数没有合理的回退值，那么这又需要 API.
的v2 入口点