我可以在不进行重大更改的情况下添加新的 REST 属性吗？

Question

我们目前有 4 种内容类型可能包含在交付中。在大约 8-12 个月内，我们可能会有另外 2-4 种内容类型。我现在正在开发一个公共 REST api，我想知道我是否可以以这样一种方式编写 api，以使未来的添加不需要版本提升？

目前我们认为delivery 会返回类似这样的 json 结果：

{
    "dateDelivered": "2016-01-01",
    "clientId": "000001",
    "contentCounts" : {
         "total" : 100,
         "articles": 75,
         "slideshows": 25
         ... // other content types as we add them
    }
    "content" : {
         "articles" : "http://api.example.com/v0/deliveries/1234/content/articles",
         "slideshows" : "http://api.example.com/v0/deliveries/1234/content/slideshows",
         ... // other content types as we add them
     }
}

这将contentCounts 和content 定义为具有每个可用内容类型的可选属性的对象。我想我可以将它定义为每个内容类型的对象数组，但我看不出这会如何真正改变任何东西。

如果将来结果对象看起来更像这样，是否有任何理由成为重大更改：

{
    "dateDelivered": "2016-01-01",
    "clientId": "000001",
    "contentCounts" : {
         "total" : 150,
         "articles": 75,
         "slideshows": 25,
         "events": 25,
         "videos": 25
    }
    "content" : {
         "articles" : "http://api.example.com/v0/deliveries/1234/content/articles",
         "slideshows" : "http://api.example.com/v0/deliveries/1234/content/slideshows",
         "events" : "http://api.example.com/v0/deliveries/1234/content/events",
         "videos" : "http://api.example.com/v0/deliveries/1234/content/videos"
     }
}

Answer 1

突破性变化是一个相对概念。 它破坏了不考虑这些更改的客户端代码。 在您的情况下，如果您的 REST API 的客户端对内容类型进行了硬编码，那么他将需要更改其代码以考虑新的内容类型。

从这个意义上说，他的代码被破坏了，因为它没有处理所有这些。 从另一个意义上说，他的代码并没有被破坏，因为只要你不删除内容类型，他的代码将继续为它支持的内容类型工作。

如果客户端代码足够聪明，可以遍历属性并对更改灵活处理，那就没问题了。

无论如何，如果你打算改变模型，你应该提到它。 无论是添加、删除还是重命名这些内容类型，如果客户知道，他可以编写一个成功使用您的 REST API 的客户端。在这种情况下，不，这不会是一个重大更改，因为它具有动态结构（内容类型可能会有所不同），而是以结构化的方式。