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

9

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

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

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

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

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

rest api api-design json Дэйв Нью
источник

Ответы:

10

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

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

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

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

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

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