Ajout à un ensemble fini d'options; un changement de rupture API?

9

Prenez un point de terminaison API HTTP qui crache le modèle de réponse suivant:

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

Le typechamp a été décrit dans la documentation comme étant l'un des Dog, Catou Fish.

L'ajout d'une nouvelle option, par exemple Rat, serait-il considéré comme une rupture de l'API?

L'ajout d'une option à une liste finie (qu'un développeur peut activer) est-il considéré comme une extension ou une modification d'une API?

rest api api-design json Dave New
la source

Réponses:

10

Si la documentation décrit ce champ comme étant un chien, un chat ou un poisson, alors oui, l'ajout d'un autre type modifie l'interface d'une manière incompatible en arrière. Il est tout à fait concevable qu'un consommateur de votre API ait écrit un code spécifique pour traiter les chiens et les chats différemment des poissons. Étant donné un type inconnu, ce consommateur ne saurait pas quoi faire de votre réponse. Mais cela dépend beaucoup de ce que ces types d'espace réservé "Chat" et "Poisson" représentent dans votre domaine de problème réel ...

Si les modifications de la liste des types possibles sont fréquentes, ou si la liste n'est pas finie, alors documenter cela en tant que tel est judicieux. Selon vos cas d'utilisation, il peut être utile d'exposer une liste de tous les types possibles en tant que point de terminaison dans votre API - de cette façon, il est clair que vous pouvez ajouter ou supprimer des types sans avoir à mettre à jour la version de l'API. Cependant, plus vos types sont dynamiques, plus il devient difficile pour les consommateurs d'API de faire quelque chose de spécifique au type. Que l'extensibilité ou la facilité d'utilisation soit plus importante dépend de vos cas d'utilisation et de votre domaine de problème.

amon
la source
Réponse fantastique - merci. Que faire si la documentation détaille les options d'un tableau intitulé "le tableau suivant décrit les animaux actuellement pris en charge par l'API". Cela n'indique-t-il pas que les options pourraient être élargies?
Dave Nouveau
1
@davenewza C'est probablement une bonne idée mais je serais plus explicite. Ne vous contentez pas d' indiquer ce que vous voulez dire - dites-le directement! J'essaierais de définir des attentes claires et d'offrir une garantie de stabilité dans les documents pour ce point de terminaison, quelque chose comme: «Le tableau suivant répertorie les animaux actuellement pris en charge, bien que nous puissions ajouter ou supprimer des animaux pris en charge à l'avenir. Lorsque cela se produit, nous mettrons à jour le numéro de version mineur de l'API. »
amon
Spécification exécutable >>> spécification documentée >>> spécification non documentée.
VoiceOfUnreason
0

Il ne serait brisé que si "Rat" pouvait être renvoyé des opérations existantes.

Si les opérations existantes ne peuvent pas retourner "Rat", l'ajout de cette nouvelle option n'aurait aucun effet.

Jon Raynor
la source