我正在创建现有 RESTful Web api 的 v2。
响应是 JSON 对象列表,大致形式如下:
[
{
name1=value1,
name2=value2,
},
{
name1=value3,
name2=value4,
}
]
我们在 v1 中观察到的一个问题是,一些客户端将按整数位置访问字段,而不是按名称。这意味着,如果我们决定在响应中添加字段(我们最初认为这是一种保持兼容性的更改),那么我们客户端的一些代码就会中断,除非我们在最后添加字段。即便如此,其他客户端代码仍然会中断,因为它们会在遇到意外的属性名称时以某种方式失败。
为了在 v2 中解决这个问题,我们正在考虑对每个响应中的字段进行随机重新排序。这将强制客户端按名称而不是按位置索引字段。
此外,我们正在考虑为每个响应添加一个随机命名的字段。这将迫使客户忽略他们不认识的字段。
虽然这听起来有些笨拙,但它确实具有我们能够添加新字段的优势,并且知道这不会破坏任何客户端是安全的。这意味着我们可以在同一个 URL 上发布对 v2.1、v2.3 等的兼容更新,这意味着我们只需要维护和支持较少数量的 API 版本。
另一种方法是在新的 URL 上发布破坏兼容性的 v3、v4,这意味着我们将不得不维护和支持许多不兼容的 API 版本,这将使我们变得更薄一些。
这是一个坏主意,如果是,为什么?我应该考虑其他类似的想法吗?
更新:前几个回复指出,如果我记录了问题(即在文档中指出可能会添加或重新排序字段),那么当我随后添加或重新排序字段时,如果客户端代码中断,我将不再受到责备。遗憾的是,我认为这对我们来说不是一个合适的选择:许多组织依赖我们 API 的功能来进行具有重大财务影响的实际交易。这些组织不以技术为导向——在客户端的最终实现涵盖了整个技术熟练度范围。我们已经做到了记录可能在 v1 的文档中添加或重新排序的字段,这显然不起作用,因为现在我们不得不发布 v2,因为许多客户,由于缺乏时间、经验或能力,仍然编写了中断的代码当我们添加新字段时。如果我现在要向界面添加字段,它会破坏十几个不同公司的界面给我们,这意味着他们(和我们)每分钟都在流血。如果我拒绝恢复更改或修复它,说“他们应该阅读文档!”,那么我很快就会失业,这是正确的。我们可能会尝试教育“失败”的合作伙伴,但这注定会失败,因为随着我们的不断发展,问题每个月都会变得越来越大。我的问题是,我是否可以系统地解决整个问题,防止这种情况发生,无论客户尝试做什么?如果我建议的技术可行,我为什么不使用它们?为什么其他人不使用它们?