Dodawanie do skończonego zestawu opcji; przełomowa zmiana API?

9

Weź punkt końcowy interfejsu API HTTP, który wyrzuca następujący model odpowiedzi:

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

typePole zostało opisane w dokumentacji jako jeden Dog, Catlub Fish.

Czy dodanie nowej opcji Ratbyłoby , powiedzmy , uważane za przełomową zmianę interfejsu API?

Czy dodanie opcji do skończonej listy (którą programista może włączyć) uważa za rozszerzenie lub modyfikację interfejsu API?

rest api api-design json Dave New
źródło

Odpowiedzi:

10

Jeśli dokumentacja opisuje to pole jako Dog, Cat lub Fish, to tak, dodanie innego typu zmienia interfejs w sposób niezgodny wstecz. Można sobie wyobrazić, że konsument interfejsu API napisał konkretny kod, który postępuje z psami i kotami inaczej niż z rybami. Biorąc pod uwagę nieznany typ, konsument nie wiedziałby, co zrobić z Twoją odpowiedzią. Zależy to jednak bardzo od tego, co te symbole zastępcze „Cat” i „Fish” reprezentują w Twojej rzeczywistej dziedzinie problemowej…

Jeśli zmiany na liście możliwych typów są częste lub jeśli lista nie jest skończona, udokumentowanie tego jako takiego jest sensowne. W zależności od przypadków użycia może być wskazane wyeksponowanie listy wszystkich możliwych typów jako punktu końcowego w interfejsie API - w ten sposób jest jasne, że można dodawać lub usuwać typy bez konieczności aktualizacji wersji interfejsu API. Jednak im bardziej dynamiczne są typy, tym trudniej jest konsumentom API zrobić coś specyficznego dla danego typu. To, czy rozszerzalność czy łatwość użytkowania jest ważniejsza, zależy od przypadków użycia i domeny problemu.

amon
źródło
Fantastyczna odpowiedź - dzięki. Co jeśli dokumentacja wyszczególnia opcje w tabeli zatytułowanej „w poniższej tabeli opisano zwierzęta obecnie obsługiwane przez interfejs API”. Czy nie oznacza to, że można rozszerzyć opcje?
Dave New
1
@davenewza To chyba dobry pomysł, ale chciałbym być bardziej wyraźny. Nie mów tylko , co masz na myśli - powiedz to bezpośrednio! Spróbuję ustalić jasne oczekiwania i zaoferować w dokumentach gwarancję stabilności dla tego punktu końcowego, coś w rodzaju: „W poniższej tabeli wymieniono obecnie obsługiwane zwierzęta, chociaż w przyszłości możemy dodawać lub usuwać obsługiwane zwierzęta. Kiedy tak się stanie, zaktualizujemy mniejszy numer wersji interfejsu API. ”
amon
Plik wykonywalny >>> udokumentowana specyfikacja >>> nieudokumentowana specyfikacja.
VoiceOfUnreason
0

Rozbiłoby się tylko, gdyby „Szczur” mógł zostać zwrócony z istniejących operacji.

Jeśli istniejące operacje nie mogą zwrócić „Rat”, wówczas dodanie tej nowej opcji nie przyniesie żadnego efektu.

Jon Raynor
źródło