Meilleures pratiques de versionnage des API RESTful : Pourquoi v1 est le numéro 1
Chris McFadden
24 mai 2017
1 min read
Points Clés
La versionnage de l'API prévient les changements disruptifs et préserve la confiance entre les fournisseurs d'API et les développeurs.
Des conventions de versionnage claires aident à éviter un mélange chaotique de versions sur les points de terminaison.
Les API RESTful associées à des URI de version simples et explicites maintiennent les intégrations intuitives pour les développeurs.
Les groupes de gouvernance garantissent la cohérence entre les équipes, empêchant les changements disruptifs accidentels.
Ce ne sont pas tous les changements qui nécessitent une nouvelle version — seulement ceux qui brisent les intégrations existantes.
Une bonne documentation est essentielle pour éviter la confusion et prévenir les changements disruptifs involontaires.
Séparer le déploiement de la mise à disposition permet aux équipes de tester et affiner en toute sécurité les points de terminaison avant de les annoncer.
Lorsque les changements disruptifs sont inévitables, ils doivent être soigneusement évalués et communiqués.
Points forts des Q&A
Pourquoi la versioning d'API est-il important?
Il empêche les changements inattendus pour les développeurs intégrant votre API, protège la confiance et assure une stabilité à long terme pour les applications qui dépendent d'un comportement cohérent.
Quelles sont les breaking changes dans une API ?
Toute modification qui change le comportement des intégrations existantes — comme la suppression de points de terminaison, la modification des valeurs par défaut, l'ajout de champs obligatoires ou la modification des formats de réponse.
Pourquoi SparkPost a-t-il choisi REST comme fondation pour leur API?
L'utilisation de REST avec HTTP et JSON facilite l'intégration pour les développeurs de différents langages (PHP, Ruby, Java, etc.) sans avoir besoin de connaissances spécialisées des systèmes sous-jacents.
Comment SparkPost a-t-il décidé de sa méthode de versioning ?
Ils ont évalué le versionnage d'en-tête Accept par rapport au versionnage URI et ont choisi le versionnage URI parce que c’est explicite, simple et plus convivial pour les développeurs.
Quel rôle joue un groupe de gouvernance API?
Il établit des normes, impose la cohérence et empêche les équipes d'introduire des modifications qui entrent en conflit avec les conventions ou qui cassent la compatibilité.
Quels types de changements ne sont pas considérés comme des breaking ?
Ajout de nouveaux paramètres optionnels, introduction de nouveaux points de terminaison, ajout de nouvelles clés dans les charges utiles JSON, ou modification des points de terminaison non publics — tout ce qui ne perturbe pas le comportement existant.
Quelles modifications sont considérées comme breaking ?
Ajout de paramètres requis, suppression d'endpoints, modification des comportements par défaut, modification de la structure de la réponse ou introduction de champs JSON requis.
Pourquoi la documentation précise est-elle essentielle ?
Il empêche les changements accidentels, aide les développeurs à comprendre le comportement et garantit que les équipes mettent à jour l'API de manière fiable. SparkPost a utilisé Markdown (API Blueprint) et GitHub pour maintenir la clarté et la transparence.
Quel est le bénéfice de séparer le déploiement de la release?
Les équipes peuvent déployer en continu de nouveaux endpoints ou améliorations en interne, les tester dans des flux de travail réels, affiner les comportements, et ne les publier publiquement qu'une fois stables — évitant ainsi une exposition prématurée et potentiellement disruptive.
Que se passe-t-il si un changement important devient nécessaire?
Il doit être rare, justifié par des avantages clairs, évalué avec soin pour l'impact sur l'utilisateur, et communiqué de manière exhaustive. Exemple : ajuster le Suppression API uniquement après avoir confirmé un effet minimal et fourni un préavis.
Alors, à quel point cela peut-il être difficile de versionner une API ? La vérité est que ce n'est pas compliqué, mais ce qui est difficile, c'est de maintenir une certaine raison en évitant de se perdre inutilement dans un nombre vertigineux de versions et de sous-versions appliquées à travers des dizaines de points de terminaison d'API avec des compatibilités peu claires.
Alors, à quel point cela peut-il être difficile de versionner une API ? La vérité est que ce n'est pas compliqué, mais ce qui est difficile, c'est de maintenir une certaine raison en évitant de se perdre inutilement dans un nombre vertigineux de versions et de sous-versions appliquées à travers des dizaines de points de terminaison d'API avec des compatibilités peu claires.
Alors, à quel point cela peut-il être difficile de versionner une API ? La vérité est que ce n'est pas compliqué, mais ce qui est difficile, c'est de maintenir une certaine raison en évitant de se perdre inutilement dans un nombre vertigineux de versions et de sous-versions appliquées à travers des dizaines de points de terminaison d'API avec des compatibilités peu claires.
Doh !
Il est juste d'admettre qu'il y a eu des fois où nous n'avons pas respecté nos idéaux de « no breaking changes » et qu'il est important d'en tirer des leçons. Une fois, nous avons décidé qu'il serait préférable pour les utilisateurs si une certaine propriété était par défaut à true au lieu de false. Après avoir déployé la modification, nous avons reçu plusieurs plaintes de la part des utilisateurs car le comportement avait changé de manière inattendue. Nous avons annulé la modification et ajouté un paramètre au niveau du compte – une approche bien plus conviviale, c'est certain.
Parfois, nous sommes tentés d'introduire des modifications majeures à la suite de corrections de bugs. Cependant, nous avons décidé de laisser ces idiosyncrasies tranquilles plutôt que de risquer de casser l’intégration des clients pour le simple fait de la cohérence.
Il y a des cas rares où nous avons pris la décision importante d'apporter une modification majeure – comme déprécier une ressource ou une méthode API – dans l'intérêt de l'ensemble de la communauté des utilisateurs et seulement après avoir confirmé qu'il n'y a que peu ou pas d'impact pour les utilisateurs. Par exemple, nous avons délibérément fait le choix de modifier le comportement de réponse de la Suppression API mais seulement après avoir soigneusement pesé les avantages et les impacts pour la communauté et avoir communiqué la modification à nos utilisateurs. Cependant, nous ne introduirons jamais une modification qui pourrait avoir la moindre possibilité d'impacter directement l'envoi d'un email en production d'un utilisateur.
Il est juste d'admettre qu'il y a eu des fois où nous n'avons pas respecté nos idéaux de « no breaking changes » et qu'il est important d'en tirer des leçons. Une fois, nous avons décidé qu'il serait préférable pour les utilisateurs si une certaine propriété était par défaut à true au lieu de false. Après avoir déployé la modification, nous avons reçu plusieurs plaintes de la part des utilisateurs car le comportement avait changé de manière inattendue. Nous avons annulé la modification et ajouté un paramètre au niveau du compte – une approche bien plus conviviale, c'est certain.
Parfois, nous sommes tentés d'introduire des modifications majeures à la suite de corrections de bugs. Cependant, nous avons décidé de laisser ces idiosyncrasies tranquilles plutôt que de risquer de casser l’intégration des clients pour le simple fait de la cohérence.
Il y a des cas rares où nous avons pris la décision importante d'apporter une modification majeure – comme déprécier une ressource ou une méthode API – dans l'intérêt de l'ensemble de la communauté des utilisateurs et seulement après avoir confirmé qu'il n'y a que peu ou pas d'impact pour les utilisateurs. Par exemple, nous avons délibérément fait le choix de modifier le comportement de réponse de la Suppression API mais seulement après avoir soigneusement pesé les avantages et les impacts pour la communauté et avoir communiqué la modification à nos utilisateurs. Cependant, nous ne introduirons jamais une modification qui pourrait avoir la moindre possibilité d'impacter directement l'envoi d'un email en production d'un utilisateur.
Il est juste d'admettre qu'il y a eu des fois où nous n'avons pas respecté nos idéaux de « no breaking changes » et qu'il est important d'en tirer des leçons. Une fois, nous avons décidé qu'il serait préférable pour les utilisateurs si une certaine propriété était par défaut à true au lieu de false. Après avoir déployé la modification, nous avons reçu plusieurs plaintes de la part des utilisateurs car le comportement avait changé de manière inattendue. Nous avons annulé la modification et ajouté un paramètre au niveau du compte – une approche bien plus conviviale, c'est certain.
Parfois, nous sommes tentés d'introduire des modifications majeures à la suite de corrections de bugs. Cependant, nous avons décidé de laisser ces idiosyncrasies tranquilles plutôt que de risquer de casser l’intégration des clients pour le simple fait de la cohérence.
Il y a des cas rares où nous avons pris la décision importante d'apporter une modification majeure – comme déprécier une ressource ou une méthode API – dans l'intérêt de l'ensemble de la communauté des utilisateurs et seulement après avoir confirmé qu'il n'y a que peu ou pas d'impact pour les utilisateurs. Par exemple, nous avons délibérément fait le choix de modifier le comportement de réponse de la Suppression API mais seulement après avoir soigneusement pesé les avantages et les impacts pour la communauté et avoir communiqué la modification à nos utilisateurs. Cependant, nous ne introduirons jamais une modification qui pourrait avoir la moindre possibilité d'impacter directement l'envoi d'un email en production d'un utilisateur.
Breaking Changes Mauvais! API Versioning Bon!
Comme toute personne ayant créé ou utilisé régulièrement une API le réalise tôt ou tard, les changements disruptifs sont très mauvais et peuvent constituer une tache très sérieuse sur une API autrement utile. Un changement disruptif est une modification du comportement d'une API qui peut rompre l'intégration d'un utilisateur et entraîner beaucoup de frustration et une perte de confiance entre le fournisseur de l'API et l'utilisateur. Les changements disruptifs exigent que les utilisateurs soient informés à l'avance (avec des excuses accompagnantes) plutôt qu'un changement qui apparaît simplement, comme une nouvelle fonctionnalité agréable. La façon d'éviter cette frustration est de versionner une API avec des assurances de la part du propriétaire de l'API qu'il n'y aura pas de changements surprenants introduits dans une seule version.
Alors, à quel point est-il difficile de versionner une API ? La vérité est que ça ne l'est pas, mais ce qui est difficile, c'est de conserver un minimum de stabilité en n'entrant pas inutilement dans un nombre vertigineux de versions et de sous-versions appliquées à travers des dizaines de points d'accès API avec des compatibilités peu claires.
Nous avons introduit la v1 de l'API il y a trois ans et nous n'avions pas réalisé qu'elle serait encore aussi forte à ce jour. Alors, comment avons-nous continué à fournir la meilleure API de livraison d'e-mails pendant plus de deux ans tout en maintenant la même version de l'API ? Cette stabilité est cruciale pour les développeurs d'applications avec des API d'e-mail dans l'infrastructure cloud, où la fiabilité et la cohérence sont primordiales. Bien qu'il y ait de nombreuses opinions différentes sur la façon de versionner les API REST, j'espère que l'histoire de notre humble mais puissant v1 pourra vous guider sur le chemin de l'éclaircissement du versionnement API.
Comme toute personne ayant créé ou utilisé régulièrement une API le réalise tôt ou tard, les changements disruptifs sont très mauvais et peuvent constituer une tache très sérieuse sur une API autrement utile. Un changement disruptif est une modification du comportement d'une API qui peut rompre l'intégration d'un utilisateur et entraîner beaucoup de frustration et une perte de confiance entre le fournisseur de l'API et l'utilisateur. Les changements disruptifs exigent que les utilisateurs soient informés à l'avance (avec des excuses accompagnantes) plutôt qu'un changement qui apparaît simplement, comme une nouvelle fonctionnalité agréable. La façon d'éviter cette frustration est de versionner une API avec des assurances de la part du propriétaire de l'API qu'il n'y aura pas de changements surprenants introduits dans une seule version.
Alors, à quel point est-il difficile de versionner une API ? La vérité est que ça ne l'est pas, mais ce qui est difficile, c'est de conserver un minimum de stabilité en n'entrant pas inutilement dans un nombre vertigineux de versions et de sous-versions appliquées à travers des dizaines de points d'accès API avec des compatibilités peu claires.
Nous avons introduit la v1 de l'API il y a trois ans et nous n'avions pas réalisé qu'elle serait encore aussi forte à ce jour. Alors, comment avons-nous continué à fournir la meilleure API de livraison d'e-mails pendant plus de deux ans tout en maintenant la même version de l'API ? Cette stabilité est cruciale pour les développeurs d'applications avec des API d'e-mail dans l'infrastructure cloud, où la fiabilité et la cohérence sont primordiales. Bien qu'il y ait de nombreuses opinions différentes sur la façon de versionner les API REST, j'espère que l'histoire de notre humble mais puissant v1 pourra vous guider sur le chemin de l'éclaircissement du versionnement API.
Comme toute personne ayant créé ou utilisé régulièrement une API le réalise tôt ou tard, les changements disruptifs sont très mauvais et peuvent constituer une tache très sérieuse sur une API autrement utile. Un changement disruptif est une modification du comportement d'une API qui peut rompre l'intégration d'un utilisateur et entraîner beaucoup de frustration et une perte de confiance entre le fournisseur de l'API et l'utilisateur. Les changements disruptifs exigent que les utilisateurs soient informés à l'avance (avec des excuses accompagnantes) plutôt qu'un changement qui apparaît simplement, comme une nouvelle fonctionnalité agréable. La façon d'éviter cette frustration est de versionner une API avec des assurances de la part du propriétaire de l'API qu'il n'y aura pas de changements surprenants introduits dans une seule version.
Alors, à quel point est-il difficile de versionner une API ? La vérité est que ça ne l'est pas, mais ce qui est difficile, c'est de conserver un minimum de stabilité en n'entrant pas inutilement dans un nombre vertigineux de versions et de sous-versions appliquées à travers des dizaines de points d'accès API avec des compatibilités peu claires.
Nous avons introduit la v1 de l'API il y a trois ans et nous n'avions pas réalisé qu'elle serait encore aussi forte à ce jour. Alors, comment avons-nous continué à fournir la meilleure API de livraison d'e-mails pendant plus de deux ans tout en maintenant la même version de l'API ? Cette stabilité est cruciale pour les développeurs d'applications avec des API d'e-mail dans l'infrastructure cloud, où la fiabilité et la cohérence sont primordiales. Bien qu'il y ait de nombreuses opinions différentes sur la façon de versionner les API REST, j'espère que l'histoire de notre humble mais puissant v1 pourra vous guider sur le chemin de l'éclaircissement du versionnement API.
REST is Best
Le SparkPost API provient de l'époque où nous étions Message Systems, avant nos aventures dans le cloud. À l'époque, nous étions occupés à finaliser les préparatifs pour le lancement bêta de Momentum 4. Il s'agissait d'une mise à niveau majeure de la version 3.x, notre MTA leader sur le marché sur site. Momentum 4 comprenait une toute nouvelle interface utilisateur, des analyses en temps réel et, surtout, une nouvelle API web pour l'injection et la génération de messages, la gestion des modèles et l'obtention de métriques d'email. Notre vision était celle d'une architecture centrée sur l'API, où même l'interface utilisateur interagirait avec des points d'accès API.
Une des premières et meilleures décisions que nous avons prises a été d'adopter un style RESTful. Depuis la fin des années 2000, le transfert d'état représentatif (REST) est le standard de facto des API cloud. Utiliser HTTP et JSON rend facile l'intégration pour les développeurs, quel que soit le langage de programmation qu'ils utilisent – PHP, Ruby et Java – pour se connecter à notre API sans connaître ou se soucier de notre technologie sous-jacente. Cependant, la construction d'APIs conçues pour le cloud à grande échelle peut poser des défis d'infrastructure inattendus, comme les limites de mise à l'échelle DNS que nous avons rencontrées dans AWS lors de la gestion de trafic API à haut volume.
Choisir d'utiliser l'architecture RESTful a été facile. Choisir une convention de versionnement n'a pas été si facile. Au début, nous avons éludé la question du versionnement en ne versionnant pas du tout la bêta. Cependant, en quelques mois, la bêta était entre les mains de quelques clients et nous avons commencé à développer notre service cloud. Le moment était venu de versionner. Nous avons évalué deux conventions de versionnement.
Approche de versionnement | Comment ça fonctionne | Compromis |
|---|---|---|
Versionnement URI | Version incluse dans le chemin d'accès de l'end-point | Explicite et facile à comprendre |
Versionnement par en-tête Accept | Version transmise via l'en-tête HTTP | Moins visible, plus complexe pour les développeurs |
La première était de mettre le versionnement directement dans l'URI et la deuxième était d'utiliser un en-tête Accept. La première option est plus explicite et moins compliquée, ce qui est plus facile pour les développeurs. Comme nous aimons les développeurs, c'était le choix logique.
Le SparkPost API provient de l'époque où nous étions Message Systems, avant nos aventures dans le cloud. À l'époque, nous étions occupés à finaliser les préparatifs pour le lancement bêta de Momentum 4. Il s'agissait d'une mise à niveau majeure de la version 3.x, notre MTA leader sur le marché sur site. Momentum 4 comprenait une toute nouvelle interface utilisateur, des analyses en temps réel et, surtout, une nouvelle API web pour l'injection et la génération de messages, la gestion des modèles et l'obtention de métriques d'email. Notre vision était celle d'une architecture centrée sur l'API, où même l'interface utilisateur interagirait avec des points d'accès API.
Une des premières et meilleures décisions que nous avons prises a été d'adopter un style RESTful. Depuis la fin des années 2000, le transfert d'état représentatif (REST) est le standard de facto des API cloud. Utiliser HTTP et JSON rend facile l'intégration pour les développeurs, quel que soit le langage de programmation qu'ils utilisent – PHP, Ruby et Java – pour se connecter à notre API sans connaître ou se soucier de notre technologie sous-jacente. Cependant, la construction d'APIs conçues pour le cloud à grande échelle peut poser des défis d'infrastructure inattendus, comme les limites de mise à l'échelle DNS que nous avons rencontrées dans AWS lors de la gestion de trafic API à haut volume.
Choisir d'utiliser l'architecture RESTful a été facile. Choisir une convention de versionnement n'a pas été si facile. Au début, nous avons éludé la question du versionnement en ne versionnant pas du tout la bêta. Cependant, en quelques mois, la bêta était entre les mains de quelques clients et nous avons commencé à développer notre service cloud. Le moment était venu de versionner. Nous avons évalué deux conventions de versionnement.
Approche de versionnement | Comment ça fonctionne | Compromis |
|---|---|---|
Versionnement URI | Version incluse dans le chemin d'accès de l'end-point | Explicite et facile à comprendre |
Versionnement par en-tête Accept | Version transmise via l'en-tête HTTP | Moins visible, plus complexe pour les développeurs |
La première était de mettre le versionnement directement dans l'URI et la deuxième était d'utiliser un en-tête Accept. La première option est plus explicite et moins compliquée, ce qui est plus facile pour les développeurs. Comme nous aimons les développeurs, c'était le choix logique.
Le SparkPost API provient de l'époque où nous étions Message Systems, avant nos aventures dans le cloud. À l'époque, nous étions occupés à finaliser les préparatifs pour le lancement bêta de Momentum 4. Il s'agissait d'une mise à niveau majeure de la version 3.x, notre MTA leader sur le marché sur site. Momentum 4 comprenait une toute nouvelle interface utilisateur, des analyses en temps réel et, surtout, une nouvelle API web pour l'injection et la génération de messages, la gestion des modèles et l'obtention de métriques d'email. Notre vision était celle d'une architecture centrée sur l'API, où même l'interface utilisateur interagirait avec des points d'accès API.
Une des premières et meilleures décisions que nous avons prises a été d'adopter un style RESTful. Depuis la fin des années 2000, le transfert d'état représentatif (REST) est le standard de facto des API cloud. Utiliser HTTP et JSON rend facile l'intégration pour les développeurs, quel que soit le langage de programmation qu'ils utilisent – PHP, Ruby et Java – pour se connecter à notre API sans connaître ou se soucier de notre technologie sous-jacente. Cependant, la construction d'APIs conçues pour le cloud à grande échelle peut poser des défis d'infrastructure inattendus, comme les limites de mise à l'échelle DNS que nous avons rencontrées dans AWS lors de la gestion de trafic API à haut volume.
Choisir d'utiliser l'architecture RESTful a été facile. Choisir une convention de versionnement n'a pas été si facile. Au début, nous avons éludé la question du versionnement en ne versionnant pas du tout la bêta. Cependant, en quelques mois, la bêta était entre les mains de quelques clients et nous avons commencé à développer notre service cloud. Le moment était venu de versionner. Nous avons évalué deux conventions de versionnement.
Approche de versionnement | Comment ça fonctionne | Compromis |
|---|---|---|
Versionnement URI | Version incluse dans le chemin d'accès de l'end-point | Explicite et facile à comprendre |
Versionnement par en-tête Accept | Version transmise via l'en-tête HTTP | Moins visible, plus complexe pour les développeurs |
La première était de mettre le versionnement directement dans l'URI et la deuxième était d'utiliser un en-tête Accept. La première option est plus explicite et moins compliquée, ce qui est plus facile pour les développeurs. Comme nous aimons les développeurs, c'était le choix logique.
API Governance
Avec une convention de versionnage sélectionnée, nous avions plus de questions. Quand devrions-nous augmenter la version ? Qu'est-ce qu'un changement radical ? Allions-nous revérsionner l'ensemble de l'API ou seulement certains points de terminaison ? Chez SparkPost, nous avons plusieurs équipes qui travaillent sur différentes parties de notre API. Au sein de ces équipes, des personnes travaillent sur différents points de terminaison à différents moments. Par conséquent, il est très important que notre API soit cohérente dans l'utilisation des conventions. C'était plus grand que le versionnage.
Nous avons établi un groupe de gouvernance comprenant des ingénieurs représentants chaque équipe, un membre de l'équipe de gestion des produits et notre CTO. Ce groupe est responsable de l'établissement, de la documentation et de l'application de nos conventions API à travers toutes les équipes. Un canal de gouvernance API dans Slack est également pratique pour des débats animés sur le sujet.
Le groupe de gouvernance a identifié un certain nombre de façons dont des changements peuvent être introduits dans l'API qui sont bénéfiques pour l'utilisateur et ne constituent pas un changement radical.
Type de changement | Considéré comme un changement radical ? | Raison |
|---|---|---|
Nouveau ressource ou point de terminaison | Non | Ne pas affecter les intégrations existantes |
Nouveau paramètre optionnel | Non | Les requêtes existantes restent valides |
Nouveau clé optionnelle JSON | Non | Les clients peuvent l'ignorer en toute sécurité |
Nouveau champ de réponse | Non | Rétrocompatible pour les utilisateurs |
Nouveau paramètre requis | Oui | Brise des requêtes existantes |
Nouveau clé POST requis | Oui | Invalide des payloads existants |
Suppression d'un point de terminaison | Oui | Les intégrations existantes échouent |
Modification du comportement par défaut | Oui | Modifie les résultats attendus |
Cela inclut :
Une nouvelle ressource ou point de terminaison API
Un nouveau paramètre optionnel
Une modification d'un point de terminaison API non public
Une nouvelle clé optionnelle dans le corps POST JSON
Une nouvelle clé retournée dans le corps de la réponse JSON
En revanche, un changement radical inclut tout ce qui pourrait casser l'intégration d'un utilisateur tel que :
Un nouveau paramètre requis
Une nouvelle clé requise dans les corps POST
Suppression d'un point de terminaison existant
Suppression d'une méthode de requête de point de terminaison existante
Un comportement interne matériellement différent d'un appel API – tel qu'un changement dans le comportement par défaut.
Avec une convention de versionnage sélectionnée, nous avions plus de questions. Quand devrions-nous augmenter la version ? Qu'est-ce qu'un changement radical ? Allions-nous revérsionner l'ensemble de l'API ou seulement certains points de terminaison ? Chez SparkPost, nous avons plusieurs équipes qui travaillent sur différentes parties de notre API. Au sein de ces équipes, des personnes travaillent sur différents points de terminaison à différents moments. Par conséquent, il est très important que notre API soit cohérente dans l'utilisation des conventions. C'était plus grand que le versionnage.
Nous avons établi un groupe de gouvernance comprenant des ingénieurs représentants chaque équipe, un membre de l'équipe de gestion des produits et notre CTO. Ce groupe est responsable de l'établissement, de la documentation et de l'application de nos conventions API à travers toutes les équipes. Un canal de gouvernance API dans Slack est également pratique pour des débats animés sur le sujet.
Le groupe de gouvernance a identifié un certain nombre de façons dont des changements peuvent être introduits dans l'API qui sont bénéfiques pour l'utilisateur et ne constituent pas un changement radical.
Type de changement | Considéré comme un changement radical ? | Raison |
|---|---|---|
Nouveau ressource ou point de terminaison | Non | Ne pas affecter les intégrations existantes |
Nouveau paramètre optionnel | Non | Les requêtes existantes restent valides |
Nouveau clé optionnelle JSON | Non | Les clients peuvent l'ignorer en toute sécurité |
Nouveau champ de réponse | Non | Rétrocompatible pour les utilisateurs |
Nouveau paramètre requis | Oui | Brise des requêtes existantes |
Nouveau clé POST requis | Oui | Invalide des payloads existants |
Suppression d'un point de terminaison | Oui | Les intégrations existantes échouent |
Modification du comportement par défaut | Oui | Modifie les résultats attendus |
Cela inclut :
Une nouvelle ressource ou point de terminaison API
Un nouveau paramètre optionnel
Une modification d'un point de terminaison API non public
Une nouvelle clé optionnelle dans le corps POST JSON
Une nouvelle clé retournée dans le corps de la réponse JSON
En revanche, un changement radical inclut tout ce qui pourrait casser l'intégration d'un utilisateur tel que :
Un nouveau paramètre requis
Une nouvelle clé requise dans les corps POST
Suppression d'un point de terminaison existant
Suppression d'une méthode de requête de point de terminaison existante
Un comportement interne matériellement différent d'un appel API – tel qu'un changement dans le comportement par défaut.
Avec une convention de versionnage sélectionnée, nous avions plus de questions. Quand devrions-nous augmenter la version ? Qu'est-ce qu'un changement radical ? Allions-nous revérsionner l'ensemble de l'API ou seulement certains points de terminaison ? Chez SparkPost, nous avons plusieurs équipes qui travaillent sur différentes parties de notre API. Au sein de ces équipes, des personnes travaillent sur différents points de terminaison à différents moments. Par conséquent, il est très important que notre API soit cohérente dans l'utilisation des conventions. C'était plus grand que le versionnage.
Nous avons établi un groupe de gouvernance comprenant des ingénieurs représentants chaque équipe, un membre de l'équipe de gestion des produits et notre CTO. Ce groupe est responsable de l'établissement, de la documentation et de l'application de nos conventions API à travers toutes les équipes. Un canal de gouvernance API dans Slack est également pratique pour des débats animés sur le sujet.
Le groupe de gouvernance a identifié un certain nombre de façons dont des changements peuvent être introduits dans l'API qui sont bénéfiques pour l'utilisateur et ne constituent pas un changement radical.
Type de changement | Considéré comme un changement radical ? | Raison |
|---|---|---|
Nouveau ressource ou point de terminaison | Non | Ne pas affecter les intégrations existantes |
Nouveau paramètre optionnel | Non | Les requêtes existantes restent valides |
Nouveau clé optionnelle JSON | Non | Les clients peuvent l'ignorer en toute sécurité |
Nouveau champ de réponse | Non | Rétrocompatible pour les utilisateurs |
Nouveau paramètre requis | Oui | Brise des requêtes existantes |
Nouveau clé POST requis | Oui | Invalide des payloads existants |
Suppression d'un point de terminaison | Oui | Les intégrations existantes échouent |
Modification du comportement par défaut | Oui | Modifie les résultats attendus |
Cela inclut :
Une nouvelle ressource ou point de terminaison API
Un nouveau paramètre optionnel
Une modification d'un point de terminaison API non public
Une nouvelle clé optionnelle dans le corps POST JSON
Une nouvelle clé retournée dans le corps de la réponse JSON
En revanche, un changement radical inclut tout ce qui pourrait casser l'intégration d'un utilisateur tel que :
Un nouveau paramètre requis
Une nouvelle clé requise dans les corps POST
Suppression d'un point de terminaison existant
Suppression d'une méthode de requête de point de terminaison existante
Un comportement interne matériellement différent d'un appel API – tel qu'un changement dans le comportement par défaut.
The Big 1.0
Comme nous avons documenté et discuté de ces conventions, nous sommes également arrivés à la conclusion qu'il était dans l'intérêt de tout le monde (y compris le nôtre !) d'éviter de faire des changements qui cassent à l'API étant donné que gérer plusieurs versions ajoute pas mal de surcharge. Nous avons décidé qu'il y avait quelques points que nous devions corriger dans notre API avant de nous engager sur la version “v1”.
Envoyer un simple email demandait beaucoup trop d'effort. Pour “garder les choses simples” nous avons mis à jour le corps POST pour garantir que les cas d'utilisation simples et complexes soient pris en charge. Le nouveau format était également plus orienté vers l'avenir. Ensuite, nous avons abordé un problème avec le point de terminaison Metrics. Ce point de terminaison utilisait un paramètre “group_by” qui changeait le format du corps de la réponse GET de sorte que la première clé serait la valeur du groupe par paramètre. Cela ne semblait pas très RESTful donc nous avons séparé chaque groupe par un point de terminaison distinct. Enfin, nous avons audité chaque point de terminaison et fait des changements mineurs ici et là pour nous assurer qu'ils étaient conformes aux normes.
Comme nous avons documenté et discuté de ces conventions, nous sommes également arrivés à la conclusion qu'il était dans l'intérêt de tout le monde (y compris le nôtre !) d'éviter de faire des changements qui cassent à l'API étant donné que gérer plusieurs versions ajoute pas mal de surcharge. Nous avons décidé qu'il y avait quelques points que nous devions corriger dans notre API avant de nous engager sur la version “v1”.
Envoyer un simple email demandait beaucoup trop d'effort. Pour “garder les choses simples” nous avons mis à jour le corps POST pour garantir que les cas d'utilisation simples et complexes soient pris en charge. Le nouveau format était également plus orienté vers l'avenir. Ensuite, nous avons abordé un problème avec le point de terminaison Metrics. Ce point de terminaison utilisait un paramètre “group_by” qui changeait le format du corps de la réponse GET de sorte que la première clé serait la valeur du groupe par paramètre. Cela ne semblait pas très RESTful donc nous avons séparé chaque groupe par un point de terminaison distinct. Enfin, nous avons audité chaque point de terminaison et fait des changements mineurs ici et là pour nous assurer qu'ils étaient conformes aux normes.
Comme nous avons documenté et discuté de ces conventions, nous sommes également arrivés à la conclusion qu'il était dans l'intérêt de tout le monde (y compris le nôtre !) d'éviter de faire des changements qui cassent à l'API étant donné que gérer plusieurs versions ajoute pas mal de surcharge. Nous avons décidé qu'il y avait quelques points que nous devions corriger dans notre API avant de nous engager sur la version “v1”.
Envoyer un simple email demandait beaucoup trop d'effort. Pour “garder les choses simples” nous avons mis à jour le corps POST pour garantir que les cas d'utilisation simples et complexes soient pris en charge. Le nouveau format était également plus orienté vers l'avenir. Ensuite, nous avons abordé un problème avec le point de terminaison Metrics. Ce point de terminaison utilisait un paramètre “group_by” qui changeait le format du corps de la réponse GET de sorte que la première clé serait la valeur du groupe par paramètre. Cela ne semblait pas très RESTful donc nous avons séparé chaque groupe par un point de terminaison distinct. Enfin, nous avons audité chaque point de terminaison et fait des changements mineurs ici et là pour nous assurer qu'ils étaient conformes aux normes.
Documentation Précise
Il est important de disposer d'une documentation API précise et utilisable pour éviter les changements cassants, qu'ils soient délibérés ou involontaires. Nous avons décidé d'utiliser une approche simple de documentation API en exploitant un langage Markdown appelé API Blueprint et gérer nos docs dans Github. Notre communauté contribue et améliore ces docs open source. Nous maintenons également un ensemble de documents non publics dans Github pour les API et les endpoints internes.
Initialement, nous avons publié nos docs sur Apiary, un excellent outil pour le prototypage et la publication de docs API. Cependant, l'intégration d'Apiary dans notre site web ne fonctionne pas sur les appareils mobiles, nous utilisons donc maintenant Jekyll pour générer des docs statiques. Nos derniers SparkPost API docs se chargent désormais rapidement et fonctionnent bien sur les appareils mobiles, ce qui est important pour les développeurs qui ne sont pas toujours assis à leur ordinateur.
Il est important de disposer d'une documentation API précise et utilisable pour éviter les changements cassants, qu'ils soient délibérés ou involontaires. Nous avons décidé d'utiliser une approche simple de documentation API en exploitant un langage Markdown appelé API Blueprint et gérer nos docs dans Github. Notre communauté contribue et améliore ces docs open source. Nous maintenons également un ensemble de documents non publics dans Github pour les API et les endpoints internes.
Initialement, nous avons publié nos docs sur Apiary, un excellent outil pour le prototypage et la publication de docs API. Cependant, l'intégration d'Apiary dans notre site web ne fonctionne pas sur les appareils mobiles, nous utilisons donc maintenant Jekyll pour générer des docs statiques. Nos derniers SparkPost API docs se chargent désormais rapidement et fonctionnent bien sur les appareils mobiles, ce qui est important pour les développeurs qui ne sont pas toujours assis à leur ordinateur.
Il est important de disposer d'une documentation API précise et utilisable pour éviter les changements cassants, qu'ils soient délibérés ou involontaires. Nous avons décidé d'utiliser une approche simple de documentation API en exploitant un langage Markdown appelé API Blueprint et gérer nos docs dans Github. Notre communauté contribue et améliore ces docs open source. Nous maintenons également un ensemble de documents non publics dans Github pour les API et les endpoints internes.
Initialement, nous avons publié nos docs sur Apiary, un excellent outil pour le prototypage et la publication de docs API. Cependant, l'intégration d'Apiary dans notre site web ne fonctionne pas sur les appareils mobiles, nous utilisons donc maintenant Jekyll pour générer des docs statiques. Nos derniers SparkPost API docs se chargent désormais rapidement et fonctionnent bien sur les appareils mobiles, ce qui est important pour les développeurs qui ne sont pas toujours assis à leur ordinateur.
Séparer le déploiement de la sortie
Nous avons appris très tôt l'astuce précieuse de séparer un déploiement d'une mise en production. De cette façon, il est possible de déployer fréquemment des modifications lorsqu'elles sont prêtes par le biais de la livraison continue et du déploiement, mais nous ne les annonçons pas toujours publiquement ou ne les documentons pas toujours en même temps. Il n'est pas rare que nous déployions un nouvel endpoint d'API ou une amélioration d'un endpoint d'API existant et l'utilisions depuis l'interface utilisateur ou avec des outils internes avant de le documenter et de le prendre en charge publiquement. Ainsi, nous pouvons y apporter quelques ajustements pour l'améliorer en termes d'utilisabilité ou de conformité aux normes sans avoir à craindre d'introduire un changement majeur redouté. Une fois que nous sommes satisfaits du changement, nous l'ajoutons à notre documentation publique.
Nous avons appris très tôt l'astuce précieuse de séparer un déploiement d'une mise en production. De cette façon, il est possible de déployer fréquemment des modifications lorsqu'elles sont prêtes par le biais de la livraison continue et du déploiement, mais nous ne les annonçons pas toujours publiquement ou ne les documentons pas toujours en même temps. Il n'est pas rare que nous déployions un nouvel endpoint d'API ou une amélioration d'un endpoint d'API existant et l'utilisions depuis l'interface utilisateur ou avec des outils internes avant de le documenter et de le prendre en charge publiquement. Ainsi, nous pouvons y apporter quelques ajustements pour l'améliorer en termes d'utilisabilité ou de conformité aux normes sans avoir à craindre d'introduire un changement majeur redouté. Une fois que nous sommes satisfaits du changement, nous l'ajoutons à notre documentation publique.
Nous avons appris très tôt l'astuce précieuse de séparer un déploiement d'une mise en production. De cette façon, il est possible de déployer fréquemment des modifications lorsqu'elles sont prêtes par le biais de la livraison continue et du déploiement, mais nous ne les annonçons pas toujours publiquement ou ne les documentons pas toujours en même temps. Il n'est pas rare que nous déployions un nouvel endpoint d'API ou une amélioration d'un endpoint d'API existant et l'utilisions depuis l'interface utilisateur ou avec des outils internes avant de le documenter et de le prendre en charge publiquement. Ainsi, nous pouvons y apporter quelques ajustements pour l'améliorer en termes d'utilisabilité ou de conformité aux normes sans avoir à craindre d'introduire un changement majeur redouté. Une fois que nous sommes satisfaits du changement, nous l'ajoutons à notre documentation publique.
