在响应 JSON (HTTP GET) 中添加新字段时是否需要更新主要 API 版本？答案

【问题标题】：Is it necessary to update major API version when adding new field in response JSON (HTTP GET)?在响应 JSON (HTTP GET) 中添加新字段时是否需要更新主要 API 版本？
【发布时间】：2020-08-11 05:05:11
【问题描述】：

例如，我创建了 API 1.0.0：

HTTP GET /getInfo 不带参数。

回复：

{
    "info1": "..."
}

发布 1.0.0 后我想添加新字段：

{
    "info1": "...",
    "info2": "..."
}

1) 我不知道 API 的客户是谁。但有可能（理论上）他们使用不灵活的反序列化/序列化，他们会遇到问题。是真实案例吗？对客户有危险吗？

2) 在这种情况下，我需要将 API 版本升级到 2.0.0 吗？还是1.1.0？

3) 关于 HTTP POST 及其带有新字段的正文的类似问题。

【问题讨论】：

哪种编程语言与您的问题最相关？
服务器语言为 C#。但我不知道谁是 API 的客户（任何语言）。
我建议以其他人更改您在应用中使用的端点响应并破坏您的代码的方式来考虑它。

标签： javascript java python c# api

【解决方案1】：

这通常不被视为重大更改，因此不，可能不需要重大版本更改。这仍然是向后兼容的，因为旧客户端在反序列化 JSON 时可以忽略这些字段。（大多数反序列化器，例如 C# 中的 Newtonsoft，已经会自动忽略任何额外的字段，因此无需更改代码）。

如果您删除了字段、添加了新的必需参数等，那么您可能需要这样做，因为这可能会破坏。

【讨论】：

我知道 C# Newtonsoft，但我不知道其他实现。

【解决方案2】：

我建议在兼容性的框架内思考。如果您的客户将不得不重写代码，因为您会破坏它们（例如缺少属性），您将需要更改版本。这也让每个人都知道发生了重大变化。

附：如果可能的话，您可能应该保留旧版本的端点，或者提前通知他们（通过响应 - 可能已经过时）您将为他们进行更改。

【讨论】：

不可能检查所有客户端。因此，解决方案是保持新旧版本。但我希望存在更好的。