Prendi un endpoint dell'API HTTP che sputa il seguente modello di risposta:
{
"type": "Dog",
"name": "Jessi",
...
}
Il campo type è stato descritto nella documentazione come uno di Dog , Cat o Fish .
Aggiungere una nuova opzione, ad esempio Rat , può essere considerata una modifica dell'API di rottura?
L'aggiunta di un'opzione a un elenco finito (che uno sviluppatore può attivare) considera un'estensione o una modifica a un'API?
Se la documentazione descrive questo campo come uno di Cane, Gatto o Pesce, allora sì, aggiungendo un altro tipo cambia l'interfaccia in un modo incompatibile all'indietro. È del tutto concepibile che un consumatore della tua API abbia scritto codice specifico per trattare cani e gatti in modo diverso rispetto al pesce. Dato un tipo sconosciuto, quel consumatore non saprebbe cosa fare con la tua risposta. Ma questo dipende molto da ciò che questi tipi di segnaposto "Cat" e "Pesce" rappresentano nel tuo reale dominio del problema ...
Se le modifiche all'elenco di possibili tipi sono frequenti, o se l'elenco non è finito, documentarlo è sensato. A seconda dei casi d'uso, potrebbe essere utile esporre un elenco di tutti i tipi possibili come endpoint nella tua API: in questo modo è 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'estensibilità o la facilità d'uso sono più importanti dipende dai casi d'uso e dal dominio del problema.
Si romperà solo se "Rat" potrebbe essere restituito da operazioni esistenti.
Se le operazioni esistenti non possono restituire "Rat", l'aggiunta di questa nuova opzione non avrebbe alcun effetto.
Leggi altre domande sui tag api-design api rest json