Додавання до кінцевого набору варіантів; Зміна порушення API?

9

Візьміть кінцеву точку API HTTP, яка випльовує таку модель відповідей:

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

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

Чи додати нову опцію, скажімо Rat, вважати нескінченною зміною API?

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

— Дейв Новий
джерело

10

Якщо в документації описано це поле як одне з собак, кішок або риб, то так, додавання іншого типу змінює інтерфейс назад-несумісним способом. Цілком можливо, що споживач вашого API написав специфічний код, що стосується собак та котів інакше, ніж із рибою. З огляду на невідомий тип, той споживач не знатиме, що робити з вашою відповіддю. Але це дуже залежить від того, що представляють ці типи заповнювачів «Кішка» та «Риба» у вашій власній проблемній області…

Якщо зміни в списку можливих типів є частими або якщо список не є кінцевим, то документування цього як такого є розумним. Залежно від випадків використання, можливо, було б добре викрити список усіх можливих типів як кінцеву точку у вашому API - таким чином зрозуміло, що ви можете додавати та видаляти типи, не оновлюючи версію API. Однак чим динамічніші ваші типи, тим складніше для споживачів API робити щось, що залежить від типу. Чи важливіше розширення чи простота використання, залежить від ваших випадків використання та вашої проблемної області.

— амон
джерело

Фантастична відповідь - спасибі. Що робити, якщо в документації детально описані параметри в одній таблиці під заголовком "у наступній таблиці описано тварин, які зараз підтримуються API". Чи це не означає, що варіанти можна було б розширити?

— Дейв Новий

1

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

— амон

Виконавча специфікація >>> документально підтверджена специфікація >>> недокументована специфікація.

— VoiceOfUnreason

0

Це буде зламати лише, якщо "Щур" можна буде повернути з існуючих операцій.

Якщо існуючі операції не можуть повернути "Щур", то додавання цієї нової опції не матиме ефекту.

— Джон Рейнор
джерело