Добавление к конечному набору опций; сломать API изменения?

9

Возьмите конечную точку HTTP API, которая выделяет следующую модель ответа:

{
    "type": "Dog",
    "name": "Jessi",
    ...
}

typeПоле было описано в документации как один из Dog, Catили Fish.

Будет ли добавление новой опции, скажем Rat, рассматриваться как критическое изменение API?

Считается ли добавление опции в конечный список (которую может включить разработчик) расширением или модификацией API?

— Дэйв Нью
источник

10

Если в документации описывается это поле как «Собака», «Кошка» или «Рыба», то да, добавление другого типа изменяет интерфейс обратно несовместимым способом. Вполне возможно, что пользователь вашего API написал специальный код для работы с собаками и кошками иначе, чем с рыбой. Учитывая неизвестный тип, этот потребитель не будет знать, что делать с вашим ответом. Но это очень сильно зависит от того, что эти типы заполнителей «Cat» и «Fish» представляют в вашей актуальной проблемной области…

Если изменения в списке возможных типов происходят часто или список не является конечным, то документирование этого как такового является разумным. В зависимости от ваших вариантов использования, может быть целесообразно представить список всех возможных типов в качестве конечной точки в вашем API - таким образом, ясно, что вы можете добавлять или удалять типы без обновления версии API. Однако чем более динамичны ваши типы, тем сложнее потребителям API сделать что-то специфичное для типа. Важность расширения или простоты использования зависит от ваших сценариев использования и проблемной области.

— Амон
источник

Фантастический ответ - спасибо. Что, если в документации подробно описаны параметры в некоторой таблице с заголовком «в следующей таблице описаны животные, в настоящее время поддерживаемые API». Не означает ли это, что варианты могут быть расширены?

— Дэйв Нью

1

@davenewza Это, вероятно, хорошая идея, но я бы сказал более четко. Не просто укажите, что вы имеете в виду, - скажите это прямо! Я бы попытался установить четкие ожидания и предложить гарантию стабильности в документах для этой конечной точки, что-то вроде: «В следующей таблице перечислены поддерживаемые в настоящее время животные, хотя мы можем добавлять или удалять поддерживаемых животных в будущем. Когда это произойдет, мы обновим дополнительный номер версии API ».

— Амон

Исполняемая спецификация >>> документированная спецификация >>> недокументированная спецификация.

— VoiceOfUnreason

0

Он сломался бы, только если «Крыса» могла быть возвращена из существующих операций.

Если существующие операции не могут вернуть «Rat», то добавление этой новой опции не будет иметь никакого эффекта.

— Джон Рейнор
источник