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 si compliqué, mais ce qui est difficile, c'est de maintenir un semblant de bon sens en évitant de se perdre dans un nombre vertigineux de versions et de sous-versions appliquées à des dizaines de points de terminaison d'API avec des compatibilités floues.
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 du lancement bêta de Momentum 4. C'était une mise à niveau majeure de la version 3.x, notre MTA sur site, leader du marché. 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 orientée API - où même l'interface utilisateur interagirait avec les points d'extrémité de l'API.
Une des meilleures décisions que nous avons prises dès le début a été d'adopter un style RESTful. Depuis la fin des années 2000, le transfert d'état représentatif (REST) basé sur les API web est devenu la norme de facto des API cloud. Utiliser HTTP et JSON facilite l'intégration pour les développeurs, peu importe le langage de programmation qu'ils utilisent – PHP, Ruby, et Java – pour s'intégrer à notre API sans connaître ou se soucier de notre technologie sous-jacente. Cependant, créer des APIs adaptées au cloud à grande échelle peut présenter des défis d'infrastructure inattendus, comme les limites de mise à l'échelle DNS que nous avons rencontrées dans AWS en gérant un trafic API à haut volume.
Choisir d'utiliser l'architecture RESTful était facile. Choisir une convention de versionnement ne l'était pas autant. Initialement, nous avons remis la question du versionnement en ne versionnant pas du tout la bêta. Cependant, en l'espace de quelques mois, la bêta était entre les mains de quelques clients et nous avons commencé à développer notre service cloud. Il était temps de versionner. Nous avons évalué deux conventions de versionnement. La première était de mettre le versionnement directement dans l'URI et la seconde é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 du lancement bêta de Momentum 4. C'était une mise à niveau majeure de la version 3.x, notre MTA sur site, leader du marché. 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 orientée API - où même l'interface utilisateur interagirait avec les points d'extrémité de l'API.
Une des meilleures décisions que nous avons prises dès le début a été d'adopter un style RESTful. Depuis la fin des années 2000, le transfert d'état représentatif (REST) basé sur les API web est devenu la norme de facto des API cloud. Utiliser HTTP et JSON facilite l'intégration pour les développeurs, peu importe le langage de programmation qu'ils utilisent – PHP, Ruby, et Java – pour s'intégrer à notre API sans connaître ou se soucier de notre technologie sous-jacente. Cependant, créer des APIs adaptées au cloud à grande échelle peut présenter des défis d'infrastructure inattendus, comme les limites de mise à l'échelle DNS que nous avons rencontrées dans AWS en gérant un trafic API à haut volume.
Choisir d'utiliser l'architecture RESTful était facile. Choisir une convention de versionnement ne l'était pas autant. Initialement, nous avons remis la question du versionnement en ne versionnant pas du tout la bêta. Cependant, en l'espace de quelques mois, la bêta était entre les mains de quelques clients et nous avons commencé à développer notre service cloud. Il était temps de versionner. Nous avons évalué deux conventions de versionnement. La première était de mettre le versionnement directement dans l'URI et la seconde é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 du lancement bêta de Momentum 4. C'était une mise à niveau majeure de la version 3.x, notre MTA sur site, leader du marché. 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 orientée API - où même l'interface utilisateur interagirait avec les points d'extrémité de l'API.
Une des meilleures décisions que nous avons prises dès le début a été d'adopter un style RESTful. Depuis la fin des années 2000, le transfert d'état représentatif (REST) basé sur les API web est devenu la norme de facto des API cloud. Utiliser HTTP et JSON facilite l'intégration pour les développeurs, peu importe le langage de programmation qu'ils utilisent – PHP, Ruby, et Java – pour s'intégrer à notre API sans connaître ou se soucier de notre technologie sous-jacente. Cependant, créer des APIs adaptées au cloud à grande échelle peut présenter des défis d'infrastructure inattendus, comme les limites de mise à l'échelle DNS que nous avons rencontrées dans AWS en gérant un trafic API à haut volume.
Choisir d'utiliser l'architecture RESTful était facile. Choisir une convention de versionnement ne l'était pas autant. Initialement, nous avons remis la question du versionnement en ne versionnant pas du tout la bêta. Cependant, en l'espace de quelques mois, la bêta était entre les mains de quelques clients et nous avons commencé à développer notre service cloud. Il était temps de versionner. Nous avons évalué deux conventions de versionnement. La première était de mettre le versionnement directement dans l'URI et la seconde é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 majeur ? Allons-nous reversionner l'ensemble de l'API ou seulement certains endpoints ? Chez SparkPost, nous avons plusieurs équipes travaillant sur différentes parties de notre API. Au sein de ces équipes, les gens travaillent sur différents endpoints à 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 incluant des ingénieurs représentant chaque équipe, un membre de l'équipe de gestion de produit et notre CTO. Ce groupe est responsable de l’établissement, de la documentation et de l'application de nos conventions API à l'échelle de toutes les équipes. Un canal de gouvernance API sur 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 d'introduire des modifications à l'API qui sont bénéfiques à l'utilisateur et ne constituent pas un changement majeur. Celles-ci incluent :
Une nouvelle ressource ou endpoint API
Un nouveau paramètre optionnel
Un changement à un endpoint API non public
Une nouvelle clé optionnelle dans le corps POST JSON
Une nouvelle clé retournée dans le corps de réponse JSON
À l'inverse, un changement majeur incluait tout ce qui pourrait casser l'intégration de l'utilisateur, tels que :
Un nouveau paramètre requis
Une nouvelle clé requise dans les corps POST
La suppression d'un endpoint existant
La suppression d'une méthode de requête d'un endpoint existant
Un comportement interne matériellement différent d'un appel API, comme un changement de 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 majeur ? Allons-nous reversionner l'ensemble de l'API ou seulement certains endpoints ? Chez SparkPost, nous avons plusieurs équipes travaillant sur différentes parties de notre API. Au sein de ces équipes, les gens travaillent sur différents endpoints à 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 incluant des ingénieurs représentant chaque équipe, un membre de l'équipe de gestion de produit et notre CTO. Ce groupe est responsable de l’établissement, de la documentation et de l'application de nos conventions API à l'échelle de toutes les équipes. Un canal de gouvernance API sur 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 d'introduire des modifications à l'API qui sont bénéfiques à l'utilisateur et ne constituent pas un changement majeur. Celles-ci incluent :
Une nouvelle ressource ou endpoint API
Un nouveau paramètre optionnel
Un changement à un endpoint API non public
Une nouvelle clé optionnelle dans le corps POST JSON
Une nouvelle clé retournée dans le corps de réponse JSON
À l'inverse, un changement majeur incluait tout ce qui pourrait casser l'intégration de l'utilisateur, tels que :
Un nouveau paramètre requis
Une nouvelle clé requise dans les corps POST
La suppression d'un endpoint existant
La suppression d'une méthode de requête d'un endpoint existant
Un comportement interne matériellement différent d'un appel API, comme un changement de 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 majeur ? Allons-nous reversionner l'ensemble de l'API ou seulement certains endpoints ? Chez SparkPost, nous avons plusieurs équipes travaillant sur différentes parties de notre API. Au sein de ces équipes, les gens travaillent sur différents endpoints à 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 incluant des ingénieurs représentant chaque équipe, un membre de l'équipe de gestion de produit et notre CTO. Ce groupe est responsable de l’établissement, de la documentation et de l'application de nos conventions API à l'échelle de toutes les équipes. Un canal de gouvernance API sur 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 d'introduire des modifications à l'API qui sont bénéfiques à l'utilisateur et ne constituent pas un changement majeur. Celles-ci incluent :
Une nouvelle ressource ou endpoint API
Un nouveau paramètre optionnel
Un changement à un endpoint API non public
Une nouvelle clé optionnelle dans le corps POST JSON
Une nouvelle clé retournée dans le corps de réponse JSON
À l'inverse, un changement majeur incluait tout ce qui pourrait casser l'intégration de l'utilisateur, tels que :
Un nouveau paramètre requis
Une nouvelle clé requise dans les corps POST
La suppression d'un endpoint existant
La suppression d'une méthode de requête d'un endpoint existant
Un comportement interne matériellement différent d'un appel API, comme un changement de 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 modifications majeures à l'API, car gérer plusieurs versions ajoute pas mal de surcharge. Nous avons décidé qu'il y avait quelques éléments que nous devions corriger dans notre API avant de nous engager à « v1 ».
Envoyer un simple e-mail demandait beaucoup trop d'efforts. 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 à l'épreuve du futur. Ensuite, nous avons résolu un problème avec l'endpoint Metrics. Cet endpoint utilisait un paramètre « group_by » qui changeait le format du corps de la réponse GET de sorte que la première clé soit la valeur du paramètre group by. Cela ne semblait pas très RESTful, nous avons donc divisé chaque group by en un endpoint séparé. Enfin, nous avons audité chaque endpoint et avons apporté quelques modifications mineures ici et là pour garantir qu'ils respectaient les 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 modifications majeures à l'API, car gérer plusieurs versions ajoute pas mal de surcharge. Nous avons décidé qu'il y avait quelques éléments que nous devions corriger dans notre API avant de nous engager à « v1 ».
Envoyer un simple e-mail demandait beaucoup trop d'efforts. 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 à l'épreuve du futur. Ensuite, nous avons résolu un problème avec l'endpoint Metrics. Cet endpoint utilisait un paramètre « group_by » qui changeait le format du corps de la réponse GET de sorte que la première clé soit la valeur du paramètre group by. Cela ne semblait pas très RESTful, nous avons donc divisé chaque group by en un endpoint séparé. Enfin, nous avons audité chaque endpoint et avons apporté quelques modifications mineures ici et là pour garantir qu'ils respectaient les 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 modifications majeures à l'API, car gérer plusieurs versions ajoute pas mal de surcharge. Nous avons décidé qu'il y avait quelques éléments que nous devions corriger dans notre API avant de nous engager à « v1 ».
Envoyer un simple e-mail demandait beaucoup trop d'efforts. 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 à l'épreuve du futur. Ensuite, nous avons résolu un problème avec l'endpoint Metrics. Cet endpoint utilisait un paramètre « group_by » qui changeait le format du corps de la réponse GET de sorte que la première clé soit la valeur du paramètre group by. Cela ne semblait pas très RESTful, nous avons donc divisé chaque group by en un endpoint séparé. Enfin, nous avons audité chaque endpoint et avons apporté quelques modifications mineures ici et là pour garantir qu'ils respectaient les 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.
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.
