运行 API，如果我更正内容类型标头，会不会对客户造成破坏？

Question

我们正在运行一个 API，有很多人在使用它。由于我的一些遗留问题，其中一个端点返回了错误的 content-type header，js而它应该是json. 我的问题是，如果我们通过交换来返回正确的值来解决这个问题，那么对于我们现有的客户来说，事情会有多严重？或者换一种说法，您是否希望许多不同的 HTTP 客户端库在看到这样的变化时抛出致命错误？

我们正在尝试确定这是一个我们可以继续进行的更改，而不必担心太多，或者我们应该仔细地向所有用户发送电子邮件并宣布一个多年的弃用期……或者介于两者之间。

这可能在一定程度上取决于正在使用的不同 HTTP 客户端的类型，因此我查看了用户代理。答案：很多不同的！以下是一些顶级的：

"okhttp/3.2.0", "python-requests/2.10.0", "Ruby", "python-requests/2.7.0", "Mozilla/5.0", "Java/1.8.0_91", "python-requests" /2.4.3", "okhttp/3.3.0", "Lucee", "Dalvik/2.1.0", "Google-HTTP-Java-Client/1.21.0", "PHP_appname", "NativeHost", "Java /1.7.0_67", "Apache-HttpClient/UNAVAILABLE", "Dalvik/1.6.0", "Web-sniffer/1.1.0", "unirest-objc/1.1"

各种不同的移动和服务器端语言库。大多数不是运行 javascript 的浏览器，但也有一些。

大多数人似乎没有注意到内容类型是错误的，但时不时会弹出一个新的支持请求，抱怨这个问题，所以我们想修复它。

Answer 1

对我们现有的客户来说，事情会有多严重？

如果他们编写的代码依赖于不正确的内容类型，它可能会完全沉没他们的战舰。

我不希望这些库抛出错误，但我希望在某些情况下，严格的库会覆盖其行为以处理不正确的 MIME 类型。

如果您的 API 在某处的请求字段中具有版本/修订值，请提高它，并在新版本中返回正确的类型，但在旧版本中继续返回不正确的类型。如果您没有这样的请求字段，现在是添加一个的好时机。

Answer 2

当看到这样的变化时，您是否希望许多不同的 HTTP 客户端库抛出致命错误？

不会。我熟悉的每个 HTTP 客户端库都会忽略内容类型标头，除非程序员专门读取该标头并对其进行处理。我可以想象一个库，其中 content-type: application/json 自动导致 json 解析器参与其中，但我不知道实际发生的任何情况。

大多数人似乎没有注意到内容类型是错误的，但时不时会弹出一个新的支持请求，抱怨这个问题，所以我们想修复它。

他们是如何注意到错误的标题的？可能值得一看，因为如果不正确的标题实际上给他们带来了问题，他们显然不仅仅是忽略它，而且如果它被修复，他们可能会遇到问题。

Answer 3

如果没有得到所有客户的认可，就很难说。我建议采用以下两种方法之一将您的 API 升级到 v.Next。

1. 扩展现有 API。将查询字符串或其他一些变量添加到您的 API 中，以表示使用 v.Next。对于使用该变量的所有请求，请使用更新后的内容类型。
2. 与当前 API 并行运行 API 的暂存或预生产实例。它应该与生产几乎相同。即使使用相同的后端。虽然这将有 v.Next 的建议更改。

在任一情况下，向您的客户传达您想要进行的更改以及目标切换日期/时间。鼓励他们在目标日期之前进行测试，以确保服务不会中断。

确保您有一个专门的页面，详细说明对 v.Next 所做的更改。这应该包含在发送给您的客户的通信中。如果您已与现有客户讨论过任何修复，请在此页面上包含这些修复。

最后，在与客户过度沟通和向他们发送垃圾邮件之间划清界限。随着更直接/紧急的优先事项出现，这些通知很容易被忽略。

FWIW，如果目前一切正常，我不会太担心。例如，如果您发现这会导致严重的安全漏洞，那么这将是推出此更改的重要原因。否则，我会等待更紧迫的事情来包含此更改。

Answer 4

这是一个会破坏的库（好吧，单个命令）的示例：

在PowerShell的cmdlet的Invoke-RestMethod使用JSON的作用是不同的。如果请求的结果是 JSON、XML 或 ATOM/RSS（我认为它基于标头），它会对其进行解析/反序列化并返回本机对象，否则返回原始数据。

因此，将编写现有代码来处理字符串（可能通过将其传递给ConvertFrom-Json），并且会突然开始失败。