Aggiunta a un set finito di opzioni; un cambiamento di rottura dell'API?

Prendi un endpoint API HTTP che sputa il seguente modello di risposta:

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

Il typecampo è stato descritto nella documentazione come uno dei Dog, Cato di Fish.

L'aggiunta di una nuova opzione, per esempio Rat, sarebbe considerata una rottura dell'API?

L'aggiunta di un'opzione a un elenco finito (che uno sviluppatore può attivare) è considerata un'estensione o una modifica a un'API?

Se la documentazione descrive questo campo come Cane, Gatto o Pesce, sì, l'aggiunta di un altro tipo modifica l'interfaccia in modo incompatibile con le versioni precedenti. È del tutto concepibile che un consumatore della tua API abbia scritto un codice specifico per trattare cani e gatti in modo diverso rispetto al pesce. Dato un tipo sconosciuto, quel consumatore non saprebbe cosa fare della tua risposta. Ma questo dipende molto da ciò che questi tipi di segnaposto "Gatto" e "Pesce" rappresentano nel dominio del tuo problema reale ...

Se le modifiche all'elenco dei possibili tipi sono frequenti o se l'elenco non è finito, è ragionevole documentarlo come tale. A seconda dei casi d'uso, potrebbe essere utile esporre un elenco di tutti i possibili tipi come endpoint nell'API: in questo modo è chiaro che è possibile aggiungere o rimuovere tipi senza dover aggiornare la versione dell'API. Tuttavia, più i tuoi tipi sono dinamici, più diventa difficile per i consumatori di API fare qualcosa di specifico per tipo. Se l'estensione o la facilità d'uso sono più importanti dipende dai casi d'uso e dal dominio del problema.

Si spezzerebbe solo se "Ratto" potesse essere restituito da operazioni esistenti.

Se le operazioni esistenti non possono restituire "Ratto", l'aggiunta di questa nuova opzione non avrebbe alcun effetto.