Contrats d'API
Un contrat est une promesse faite à du code que vous ne contrôlez pas et que vous ne pouvez pas corriger. C'est ce qui rend les changements d'API différents d'un refactoring interne : le coût d'une erreur est payé par quelqu'un d'autre, à un moment que vous ne choisissez pas.
Conception
Nommez les ressources comme des noms et laissez la méthode porter le verbe. Modélisez la chose, pas l'écran qui l'affiche actuellement — une charge utile façonnée autour de l'interface d'aujourd'hui devient erronée lors de la prochaine refonte.
Soyez délibéré sur ce que vous exposez. Chaque champ que vous retournez est un champ que vous devez continuer à retourner. Les identifiants internes, les numéros de version de ligne et les détails d'implémentation laissent votre schéma s'infiltrer dans le code de l'appelant et le figent là.
Rendez les opérations idempotentes là où l'appelant peut réessayer, c'est-à-dire toute opération accessible via un réseau. Donnez à l'appelant une clé d'idempotence pour tout ce qui crée ou facture, afin qu'une nouvelle tentative après un délai d'attente ne puisse pas le dupliquer.
Renvoie un modèle d'erreur cohérent : un code stable lisible par machine, un message lisible par l'humain et le champ auquel se rapporte un échec de validation. Les appelants se basent sur le code, donc il fait partie du contrat — changer un code est un changement cassant même si la forme reste inchangée.
Paginer chaque liste, dès la première version. Un endpoint qui retourne tout fonctionne jusqu'à ce que la table grandisse, puis échoue pour le client avec le plus de données. Préférez un curseur à un décalage (offset) lorsque les lignes sont insérées simultanément.
Ce qui casse un appelant
Cassant, quoi que permette le langage de schéma :
- Supprimer ou renommer un champ, un endpoint, une méthode ou une valeur d'énumération.
- Rendre un champ de requête facultatif obligatoire, ou restreindre ce qu'un champ accepte.
- Changer un type, y compris entier en chaîne et une valeur unique en liste.
- Changer le sens d'un champ existant tout en conservant son nom et son type — le pire, car rien n'échoue bruyamment et les données sont silencieusement erronées.
- Ajouter un nouveau champ obligatoire à une requête.
- Changer un code d'erreur ou un statut HTTP pour une condition existante.
- Resserer une valeur par défaut, ou modifier ce qui se passe lorsqu'un champ est omis.
Sûr : ajouter un champ de requête facultatif, ajouter un champ de réponse, ajouter un nouveau endpoint ou une nouvelle méthode, ajouter une valeur d'énumération uniquement si chaque consommateur tolère déjà les valeurs inconnues — vérifiez cela plutôt que de le supposer.
Dans protobuf, ne réutilisez ni ne renumérotez jamais une balise de champ, et réservez la balise et le nom lorsque vous supprimez un champ. Une balise réutilisée décode les anciennes données dans le nouveau champ et les corrompt silencieusement.
Modifier un contrat en toute sécurité
Ajoutez avant de supprimer, et laissez les deux fonctionner pendant au moins une version :
- Ajoutez le nouveau champ ou la nouvelle méthode à côté de l'ancien.
- Écrivez les deux, lisez le nouveau avec un repli sur l'ancien.
- Migrez les consommateurs et confirmez que chacun a bougé.
- Supprimez l'ancien chemin dans une version ultérieure.
Versionnez lorsque la ressource change réellement de sens, pas pour chaque ajout. Une version par changement multiplie la surface que vous devez maintenir en vie.
Ordre de déploiement
Le code généré et les serveurs sont déployés séparément, et l'écart est là où résident les pannes. Déployez d'abord le côté qui tolère les deux formes : les consommateurs qui acceptent le nouveau champ avant que les producteurs ne l'émettent, les producteurs qui acceptent la nouvelle requête avant que les appelants ne l'envoient.
Lorsqu'un schéma est partagé via une passerelle, un proxy ou des clients générés, chaque composant du chemin doit être régénéré et redéployé. Un champ ajouté au service mais pas à la couche qui le précède disparaît avant d'atteindre l'appelant, et les propres tests du service ne le remarqueront pas.
Vérifier
Vérifiez les consommateurs réels avant de modifier une forme — greppez les appelants plutôt que de vous fier à la documentation du contrat.
Testez le contrat lui-même : un test qui vérifie la forme sérialisée détecte un renommage accidentel qu'un test unitaire sur le gestionnaire manquera complètement.