我可以添加新的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。在这种情况下，不，这不会是一个突破性的改变，因为它具有动态结构（内容类型可以变化），但是以结构化的方式。