Могу ли я добавить новые свойства REST без внесения изменений?

Question

В настоящее время у нас есть 4 типа контента, которые могут быть включены в поставку. Примерно через 8-12 месяцев у нас, вероятно, будут еще 2-4 типа контента. Я сейчас работаю над публичным REST api и задаюсь вопросом, могу ли я написать api таким образом, чтобы в будущих дополнениях не требовалась версия bump?

В настоящее время мы Подумав 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. В этом случае НЕТ, это не было бы изменением, поскольку имеет динамическую структуру (типы контента могут меняться), но структурированным образом.