Hinzufügen zu einer endlichen Reihe von Optionen; eine API brechen Änderung?

9

Nehmen Sie einen HTTP-API-Endpunkt, der das folgende Antwortmodell ausspuckt:

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

Das typeFeld wurde als eine der in der Dokumentation beschrieben Dog, Catoder Fish.

Würde das Hinzufügen einer neuen Option Ratbeispielsweise als brechende API-Änderung angesehen?

Wird das Hinzufügen einer Option zu einer endlichen Liste (die ein Entwickler möglicherweise einschaltet) als Erweiterung oder Änderung einer API betrachtet?

rest api api-design json Dave New
quelle

Antworten:

10

Wenn in der Dokumentation dieses Feld als "Hund", "Katze" oder "Fisch" beschrieben wird, ändert das Hinzufügen eines anderen Typs die Benutzeroberfläche auf eine rückwärts inkompatible Weise. Es ist durchaus denkbar, dass ein Verbraucher Ihrer API einen spezifischen Code geschrieben hat, um mit Hunden und Katzen anders umzugehen als mit Fischen. Bei einem unbekannten Typ würde dieser Verbraucher nicht wissen, was er mit Ihrer Antwort tun soll. Dies hängt jedoch sehr davon ab, was diese Platzhaltertypen „Katze“ und „Fisch“ in Ihrer eigentlichen Problemdomäne darstellen.

Wenn Änderungen an der Liste der möglichen Typen häufig sind oder wenn die Liste nicht endlich ist, ist es sinnvoll, dies als solche zu dokumentieren. Abhängig von Ihren Anwendungsfällen kann es sinnvoll sein, eine Liste aller möglichen Typen als Endpunkt in Ihrer API bereitzustellen. Auf diese Weise können Sie Typen hinzufügen oder entfernen, ohne die API-Version aktualisieren zu müssen. Je dynamischer Ihre Typen sind, desto schwieriger wird es für API-Konsumenten, etwas Typspezifisches zu tun. Ob Erweiterbarkeit oder Benutzerfreundlichkeit wichtiger sind, hängt von Ihren Anwendungsfällen und Ihrer Problemdomäne ab.

amon
quelle
Fantastische Antwort - danke. Was passiert, wenn in der Dokumentation die Optionen in einer Tabelle mit dem Titel "Die folgende Tabelle beschreibt die derzeit von der API unterstützten Tiere " aufgeführt sind. Bedeutet dies nicht, dass die Optionen erweitert werden könnten?
Dave New
1
@davenewza Das ist wahrscheinlich eine gute Idee, aber ich würde expliziter sein. Geben Sie nicht nur an, was Sie meinen - sagen Sie es direkt! Ich würde versuchen, klare Erwartungen zu setzen und in den Dokumenten eine Stabilitätsgarantie für diesen Endpunkt anzubieten , etwa: „In der folgenden Tabelle sind die derzeit unterstützten Tiere aufgeführt, obwohl wir möglicherweise in Zukunft unterstützte Tiere hinzufügen oder entfernen. In diesem Fall aktualisieren wir die Nebenversionsnummer der API. “
Amon
Ausführbare Spezifikation >>> dokumentierte Spezifikation >>> undokumentierte Spezifikation.
VoiceOfUnreason
0

Es würde nur brechen, wenn "Ratte" aus bestehenden Operationen zurückgegeben werden könnte.

Wenn vorhandene Vorgänge "Rat" nicht zurückgeben können, hat das Hinzufügen dieser neuen Option keine Auswirkung.

Jon Raynor
quelle